1 /*
2 * Copyright (C) 2017, Thomas Wolf <thomas.wolf@paranor.ch>
3 * and other copyright owners as documented in the project's IP log.
4 *
5 * This program and the accompanying materials are made available
6 * under the terms of the Eclipse Distribution License v1.0 which
7 * accompanies this distribution, is reproduced below, and is
8 * available at http://www.eclipse.org/org/documents/edl-v10.php
9 *
10 * All rights reserved.
11 *
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
14 * conditions are met:
15 *
16 * - Redistributions of source code must retain the above copyright
17 * notice, this list of conditions and the following disclaimer.
18 *
19 * - Redistributions in binary form must reproduce the above
20 * copyright notice, this list of conditions and the following
21 * disclaimer in the documentation and/or other materials provided
22 * with the distribution.
23 *
24 * - Neither the name of the Eclipse Foundation, Inc. nor the
25 * names of its contributors may be used to endorse or promote
26 * products derived from this software without specific prior
27 * written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
30 * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
31 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
32 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
34 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
35 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
36 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
37 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
38 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
39 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
40 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
41 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 */
43
44 package org.eclipse.jgit.lib;
45
46 import java.util.List;
47 import java.util.concurrent.TimeUnit;
48
49 import org.eclipse.jgit.annotations.NonNull;
50 import org.eclipse.jgit.transport.RefSpec;
51
52 /**
53 * Something that knows how to convert plain strings from a git
54 * {@link org.eclipse.jgit.lib.Config} to typed values.
55 *
56 * @since 4.9
57 */
58 public interface TypedConfigGetter {
59
60 /**
61 * Get a boolean value from a git {@link org.eclipse.jgit.lib.Config}.
62 *
63 * @param config
64 * to get the value from
65 * @param section
66 * section the key is grouped within.
67 * @param subsection
68 * subsection name, such a remote or branch name.
69 * @param name
70 * name of the key to get.
71 * @param defaultValue
72 * default value to return if no value was present.
73 * @return true if any value or defaultValue is true, false for missing or
74 * explicit false
75 */
76 boolean getBoolean(Config config, String section, String subsection,
77 String name, boolean defaultValue);
78
79 /**
80 * Parse an enumeration from a git {@link org.eclipse.jgit.lib.Config}.
81 *
82 * @param config
83 * to get the value from
84 * @param all
85 * all possible values in the enumeration which should be
86 * recognized. Typically {@code EnumType.values()}.
87 * @param section
88 * section the key is grouped within.
89 * @param subsection
90 * subsection name, such a remote or branch name.
91 * @param name
92 * name of the key to get.
93 * @param defaultValue
94 * default value to return if no value was present.
95 * @return the selected enumeration value, or {@code defaultValue}.
96 */
97 <T extends Enum<?>> T getEnum(Config config, T[] all, String section,
98 String subsection, String name, T defaultValue);
99
100 /**
101 * Obtain an integer value from a git {@link org.eclipse.jgit.lib.Config}.
102 *
103 * @param config
104 * to get the value from
105 * @param section
106 * section the key is grouped within.
107 * @param subsection
108 * subsection name, such a remote or branch name.
109 * @param name
110 * name of the key to get.
111 * @param defaultValue
112 * default value to return if no value was present.
113 * @return an integer value from the configuration, or defaultValue.
114 */
115 int getInt(Config config, String section, String subsection, String name,
116 int defaultValue);
117
118 /**
119 * Obtain a long value from a git {@link org.eclipse.jgit.lib.Config}.
120 *
121 * @param config
122 * to get the value from
123 * @param section
124 * section the key is grouped within.
125 * @param subsection
126 * subsection name, such a remote or branch name.
127 * @param name
128 * name of the key to get.
129 * @param defaultValue
130 * default value to return if no value was present.
131 * @return a long value from the configuration, or defaultValue.
132 */
133 long getLong(Config config, String section, String subsection, String name,
134 long defaultValue);
135
136 /**
137 * Parse a numerical time unit, such as "1 minute", from a git
138 * {@link org.eclipse.jgit.lib.Config}.
139 *
140 * @param config
141 * to get the value from
142 * @param section
143 * section the key is in.
144 * @param subsection
145 * subsection the key is in, or null if not in a subsection.
146 * @param name
147 * the key name.
148 * @param defaultValue
149 * default value to return if no value was present.
150 * @param wantUnit
151 * the units of {@code defaultValue} and the return value, as
152 * well as the units to assume if the value does not contain an
153 * indication of the units.
154 * @return the value, or {@code defaultValue} if not set, expressed in
155 * {@code units}.
156 */
157 long getTimeUnit(Config config, String section, String subsection,
158 String name, long defaultValue, TimeUnit wantUnit);
159
160
161 /**
162 * Parse a list of {@link org.eclipse.jgit.transport.RefSpec}s from a git
163 * {@link org.eclipse.jgit.lib.Config}.
164 *
165 * @param config
166 * to get the list from
167 * @param section
168 * section the key is in.
169 * @param subsection
170 * subsection the key is in, or null if not in a subsection.
171 * @param name
172 * the key name.
173 * @return a possibly empty list of
174 * {@link org.eclipse.jgit.transport.RefSpec}s
175 */
176 @NonNull
177 List<RefSpec> getRefSpecs(Config config, String section, String subsection,
178 String name);
179 }