001 /*
002 * Copyright (c) OSGi Alliance (2001, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.metatype;
017
018 /**
019 * An interface to describe an attribute.
020 *
021 * <p>
022 * An <code>AttributeDefinition</code> object defines a description of the data
023 * type of a property/attribute.
024 *
025 * @version $Revision: 5673 $
026 */
027 public interface AttributeDefinition {
028 /**
029 * The <code>STRING</code> (1) type.
030 *
031 * <p>
032 * Attributes of this type should be stored as <code>String</code>,
033 * <code>Vector</code> with <code>String</code> or <code>String[]</code> objects,
034 * depending on the <code>getCardinality()</code> value.
035 */
036 public static final int STRING = 1;
037 /**
038 * The <code>LONG</code> (2) type.
039 *
040 * Attributes of this type should be stored as <code>Long</code>,
041 * <code>Vector</code> with <code>Long</code> or <code>long[]</code> objects,
042 * depending on the <code>getCardinality()</code> value.
043 */
044 public static final int LONG = 2;
045 /**
046 * The <code>INTEGER</code> (3) type.
047 *
048 * Attributes of this type should be stored as <code>Integer</code>,
049 * <code>Vector</code> with <code>Integer</code> or <code>int[]</code> objects,
050 * depending on the <code>getCardinality()</code> value.
051 */
052 public static final int INTEGER = 3;
053 /**
054 * The <code>SHORT</code> (4) type.
055 *
056 * Attributes of this type should be stored as <code>Short</code>,
057 * <code>Vector</code> with <code>Short</code> or <code>short[]</code> objects,
058 * depending on the <code>getCardinality()</code> value.
059 */
060 public static final int SHORT = 4;
061 /**
062 * The <code>CHARACTER</code> (5) type.
063 *
064 * Attributes of this type should be stored as <code>Character</code>,
065 * <code>Vector</code> with <code>Character</code> or <code>char[]</code> objects,
066 * depending on the <code>getCardinality()</code> value.
067 */
068 public static final int CHARACTER = 5;
069 /**
070 * The <code>BYTE</code> (6) type.
071 *
072 * Attributes of this type should be stored as <code>Byte</code>,
073 * <code>Vector</code> with <code>Byte</code> or <code>byte[]</code> objects,
074 * depending on the <code>getCardinality()</code> value.
075 */
076 public static final int BYTE = 6;
077 /**
078 * The <code>DOUBLE</code> (7) type.
079 *
080 * Attributes of this type should be stored as <code>Double</code>,
081 * <code>Vector</code> with <code>Double</code> or <code>double[]</code> objects,
082 * depending on the <code>getCardinality()</code> value.
083 */
084 public static final int DOUBLE = 7;
085 /**
086 * The <code>FLOAT</code> (8) type.
087 *
088 * Attributes of this type should be stored as <code>Float</code>,
089 * <code>Vector</code> with <code>Float</code> or <code>float[]</code> objects,
090 * depending on the <code>getCardinality()</code> value.
091 */
092 public static final int FLOAT = 8;
093 /**
094 * The <code>BIGINTEGER</code> (9) type.
095 *
096 * Attributes of this type should be stored as <code>BigInteger</code>,
097 * <code>Vector</code> with <code>BigInteger</code> or <code>BigInteger[]</code>
098 * objects, depending on the <code>getCardinality()</code> value.
099 *
100 * @deprecated As of 1.1.
101 */
102 public static final int BIGINTEGER = 9;
103 /**
104 * The <code>BIGDECIMAL</code> (10) type.
105 *
106 * Attributes of this type should be stored as <code>BigDecimal</code>,
107 * <code>Vector</code> with <code>BigDecimal</code> or <code>BigDecimal[]</code>
108 * objects depending on <code>getCardinality()</code>.
109 *
110 * @deprecated As of 1.1.
111 */
112 public static final int BIGDECIMAL = 10;
113 /**
114 * The <code>BOOLEAN</code> (11) type.
115 *
116 * Attributes of this type should be stored as <code>Boolean</code>,
117 * <code>Vector</code> with <code>Boolean</code> or <code>boolean[]</code> objects
118 * depending on <code>getCardinality()</code>.
119 */
120 public static final int BOOLEAN = 11;
121
122 /**
123 * Get the name of the attribute. This name may be localized.
124 *
125 * @return The localized name of the definition.
126 */
127 public String getName();
128
129 /**
130 * Unique identity for this attribute.
131 *
132 * Attributes share a global namespace in the registry. E.g. an attribute
133 * <code>cn</code> or <code>commonName</code> must always be a <code>String</code>
134 * and the semantics are always a name of some object. They share this
135 * aspect with LDAP/X.500 attributes. In these standards the OSI Object
136 * Identifier (OID) is used to uniquely identify an attribute. If such an
137 * OID exists, (which can be requested at several standard organisations and
138 * many companies already have a node in the tree) it can be returned here.
139 * Otherwise, a unique id should be returned which can be a Java class name
140 * (reverse domain name) or generated with a GUID algorithm. Note that all
141 * LDAP defined attributes already have an OID. It is strongly advised to
142 * define the attributes from existing LDAP schemes which will give the OID.
143 * Many such schemes exist ranging from postal addresses to DHCP parameters.
144 *
145 * @return The id or oid
146 */
147 public String getID();
148
149 /**
150 * Return a description of this attribute.
151 *
152 * The description may be localized and must describe the semantics of this
153 * type and any constraints.
154 *
155 * @return The localized description of the definition.
156 */
157 public String getDescription();
158
159 /**
160 * Return the cardinality of this attribute.
161 *
162 * The OSGi environment handles multi valued attributes in arrays ([]) or in
163 * <code>Vector</code> objects. The return value is defined as follows:
164 *
165 * <pre>
166 *
167 * x = Integer.MIN_VALUE no limit, but use Vector
168 * x < 0 -x = max occurrences, store in Vector
169 * x > 0 x = max occurrences, store in array []
170 * x = Integer.MAX_VALUE no limit, but use array []
171 * x = 0 1 occurrence required
172 *
173 * </pre>
174 *
175 * @return The cardinality of this attribute.
176 */
177 public int getCardinality();
178
179 /**
180 * Return the type for this attribute.
181 *
182 * <p>
183 * Defined in the following constants which map to the appropriate Java
184 * type. <code>STRING</code>,<code>LONG</code>,<code>INTEGER</code>,
185 * <code>CHAR</code>,<code>BYTE</code>,<code>DOUBLE</code>,<code>FLOAT</code>,
186 * <code>BOOLEAN</code>.
187 *
188 * @return The type for this attribute.
189 */
190 public int getType();
191
192 /**
193 * Return a list of option values that this attribute can take.
194 *
195 * <p>
196 * If the function returns <code>null</code>, there are no option values
197 * available.
198 *
199 * <p>
200 * Each value must be acceptable to validate() (return "") and must be a
201 * <code>String</code> object that can be converted to the data type defined
202 * by getType() for this attribute.
203 *
204 * <p>
205 * This list must be in the same sequence as <code>getOptionLabels()</code>.
206 * I.e. for each index i in <code>getOptionValues</code>, i in
207 * <code>getOptionLabels()</code> should be the label.
208 *
209 * <p>
210 * For example, if an attribute can have the value male, female, unknown,
211 * this list can return
212 * <code>new String[] { "male", "female", "unknown" }</code>.
213 *
214 * @return A list values
215 */
216 public String[] getOptionValues();
217
218 /**
219 * Return a list of labels of option values.
220 *
221 * <p>
222 * The purpose of this method is to allow menus with localized labels. It is
223 * associated with <code>getOptionValues</code>. The labels returned here are
224 * ordered in the same way as the values in that method.
225 *
226 * <p>
227 * If the function returns <code>null</code>, there are no option labels
228 * available.
229 * <p>
230 * This list must be in the same sequence as the <code>getOptionValues()</code>
231 * method. I.e. for each index i in <code>getOptionLabels</code>, i in
232 * <code>getOptionValues()</code> should be the associated value.
233 *
234 * <p>
235 * For example, if an attribute can have the value male, female, unknown,
236 * this list can return (for dutch)
237 * <code>new String[] { "Man", "Vrouw", "Onbekend" }</code>.
238 *
239 * @return A list values
240 */
241 public String[] getOptionLabels();
242
243 /**
244 * Validate an attribute in <code>String</code> form.
245 *
246 * An attribute might be further constrained in value. This method will
247 * attempt to validate the attribute according to these constraints. It can
248 * return three different values:
249 *
250 * <pre>
251 * null No validation present
252 * "" No problems detected
253 * "..." A localized description of why the value is wrong
254 * </pre>
255 *
256 * @param value The value before turning it into the basic data type
257 * @return <code>null</code>, "", or another string
258 */
259 public String validate(String value);
260
261 /**
262 * Return a default for this attribute.
263 *
264 * The object must be of the appropriate type as defined by the cardinality
265 * and <code>getType()</code>. The return type is a list of <code>String</code>
266 * objects that can be converted to the appropriate type. The cardinality of
267 * the return array must follow the absolute cardinality of this type. E.g.
268 * if the cardinality = 0, the array must contain 1 element. If the
269 * cardinality is 1, it must contain 0 or 1 elements. If it is -5, it must
270 * contain from 0 to max 5 elements. Note that the special case of a 0
271 * cardinality, meaning a single value, does not allow arrays or vectors of
272 * 0 elements.
273 *
274 * @return Return a default value or <code>null</code> if no default exists.
275 */
276 public String[] getDefaultValue();
277 }