AttributeDefinition


1   /*
2    * $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/AttributeDefinition.java,v 1.13 2006/06/16 16:31:23 hargrave Exp $
3    *
4    * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
5    * 
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.osgi.service.metatype;
19  
20  /**
21   * An interface to describe an attribute.
22   * 
23   * <p>
24   * An <code>AttributeDefinition</code> object defines a description of the data
25   * type of a property/attribute.
26   * 
27   * @version $Revision: 1.13 $
28   */
29  public interface AttributeDefinition {
30      /**
31       * The <code>STRING</code> (1) type.
32       * 
33       * <p>
34       * Attributes of this type should be stored as <code>String</code>,
35       * <code>Vector</code> with <code>String</code> or <code>String[]</code> objects,
36       * depending on the <code>getCardinality()</code> value.
37       */
38      public static final int STRING      = 1;
39      /**
40       * The <code>LONG</code> (2) type.
41       * 
42       * Attributes of this type should be stored as <code>Long</code>,
43       * <code>Vector</code> with <code>Long</code> or <code>long[]</code> objects,
44       * depending on the <code>getCardinality()</code> value.
45       */
46      public static final int LONG        = 2;
47      /**
48       * The <code>INTEGER</code> (3) type.
49       * 
50       * Attributes of this type should be stored as <code>Integer</code>,
51       * <code>Vector</code> with <code>Integer</code> or <code>int[]</code> objects,
52       * depending on the <code>getCardinality()</code> value.
53       */
54      public static final int INTEGER     = 3;
55      /**
56       * The <code>SHORT</code> (4) type.
57       * 
58       * Attributes of this type should be stored as <code>Short</code>,
59       * <code>Vector</code> with <code>Short</code> or <code>short[]</code> objects,
60       * depending on the <code>getCardinality()</code> value.
61       */
62      public static final int SHORT       = 4;
63      /**
64       * The <code>CHARACTER</code> (5) type.
65       * 
66       * Attributes of this type should be stored as <code>Character</code>,
67       * <code>Vector</code> with <code>Character</code> or <code>char[]</code> objects,
68       * depending on the <code>getCardinality()</code> value.
69       */
70      public static final int CHARACTER   = 5;
71      /**
72       * The <code>BYTE</code> (6) type.
73       * 
74       * Attributes of this type should be stored as <code>Byte</code>,
75       * <code>Vector</code> with <code>Byte</code> or <code>byte[]</code> objects,
76       * depending on the <code>getCardinality()</code> value.
77       */
78      public static final int BYTE        = 6;
79      /**
80       * The <code>DOUBLE</code> (7) type.
81       * 
82       * Attributes of this type should be stored as <code>Double</code>,
83       * <code>Vector</code> with <code>Double</code> or <code>double[]</code> objects,
84       * depending on the <code>getCardinality()</code> value.
85       */
86      public static final int DOUBLE      = 7;
87      /**
88       * The <code>FLOAT</code> (8) type.
89       * 
90       * Attributes of this type should be stored as <code>Float</code>,
91       * <code>Vector</code> with <code>Float</code> or <code>float[]</code> objects,
92       * depending on the <code>getCardinality()</code> value.
93       */
94      public static final int FLOAT       = 8;
95      /**
96       * The <code>BIGINTEGER</code> (9) type.
97       * 
98       * Attributes of this type should be stored as <code>BigInteger</code>,
99       * <code>Vector</code> with <code>BigInteger</code> or <code>BigInteger[]</code>
100      * objects, depending on the <code>getCardinality()</code> value.
101      * 
102      * @deprecated As of 1.1.
103      */
104     public static final int BIGINTEGER  = 9;
105     /**
106      * The <code>BIGDECIMAL</code> (10) type.
107      * 
108      * Attributes of this type should be stored as <code>BigDecimal</code>,
109      * <code>Vector</code> with <code>BigDecimal</code> or <code>BigDecimal[]</code>
110      * objects depending on <code>getCardinality()</code>.
111      * 
112      * @deprecated As of 1.1.
113      */
114     public static final int BIGDECIMAL  = 10;
115     /**
116      * The <code>BOOLEAN</code> (11) type.
117      * 
118      * Attributes of this type should be stored as <code>Boolean</code>,
119      * <code>Vector</code> with <code>Boolean</code> or <code>boolean[]</code> objects
120      * depending on <code>getCardinality()</code>.
121      */
122     public static final int BOOLEAN     = 11;
123 
124     /**
125      * Get the name of the attribute. This name may be localized.
126      * 
127      * @return The localized name of the definition.
128      */
129     public String   getName();
130 
131     /**
132      * Unique identity for this attribute.
133      * 
134      * Attributes share a global namespace in the registry. E.g. an attribute
135      * <code>cn</code> or <code>commonName</code> must always be a <code>String</code>
136      * and the semantics are always a name of some object. They share this
137      * aspect with LDAP/X.500 attributes. In these standards the OSI Object
138      * Identifier (OID) is used to uniquely identify an attribute. If such an
139      * OID exists, (which can be requested at several standard organisations and
140      * many companies already have a node in the tree) it can be returned here.
141      * Otherwise, a unique id should be returned which can be a Java class name
142      * (reverse domain name) or generated with a GUID algorithm. Note that all
143      * LDAP defined attributes already have an OID. It is strongly advised to
144      * define the attributes from existing LDAP schemes which will give the OID.
145      * Many such schemes exist ranging from postal addresses to DHCP parameters.
146      * 
147      * @return The id or oid
148      */
149     public String   getID();
150 
151     /**
152      * Return a description of this attribute.
153      * 
154      * The description may be localized and must describe the semantics of this
155      * type and any constraints.
156      * 
157      * @return The localized description of the definition.
158      */
159     public String   getDescription();
160 
161     /**
162      * Return the cardinality of this attribute.
163      * 
164      * The OSGi environment handles multi valued attributes in arrays ([]) or in
165      * <code>Vector</code> objects. The return value is defined as follows:
166      * 
167      * <pre>
168      * 
169      *    x = Integer.MIN_VALUE    no limit, but use Vector
170      *    x &lt; 0                    -x = max occurrences, store in Vector
171      *    x &gt; 0                     x = max occurrences, store in array []
172      *    x = Integer.MAX_VALUE    no limit, but use array []
173      *    x = 0                     1 occurrence required
174      *  
175      * </pre>
176      * 
177      * @return The cardinality of this attribute. 
178      */
179     public int getCardinality();
180 
181     /**
182      * Return the type for this attribute.
183      * 
184      * <p>
185      * Defined in the following constants which map to the appropriate Java
186      * type. <code>STRING</code>,<code>LONG</code>,<code>INTEGER</code>,
187      * <code>CHAR</code>,<code>BYTE</code>,<code>DOUBLE</code>,<code>FLOAT</code>,
188      * <code>BOOLEAN</code>.
189      *
190      * @return The type for this attribute.
191      */
192     public int getType();
193 
194     /**
195      * Return a list of option values that this attribute can take.
196      * 
197      * <p>
198      * If the function returns <code>null</code>, there are no option values
199      * available.
200      * 
201      * <p>
202      * Each value must be acceptable to validate() (return "") and must be a
203      * <code>String</code> object that can be converted to the data type defined
204      * by getType() for this attribute.
205      * 
206      * <p>
207      * This list must be in the same sequence as <code>getOptionLabels()</code>.
208      * I.e. for each index i in <code>getOptionValues</code>, i in
209      * <code>getOptionLabels()</code> should be the label.
210      * 
211      * <p>
212      * For example, if an attribute can have the value male, female, unknown,
213      * this list can return
214      * <code>new String[] { "male", "female", "unknown" }</code>.
215      * 
216      * @return A list values
217      */
218     public String  [] getOptionValues();
219 
220     /**
221      * Return a list of labels of option values.
222      * 
223      * <p>
224      * The purpose of this method is to allow menus with localized labels. It is
225      * associated with <code>getOptionValues</code>. The labels returned here are
226      * ordered in the same way as the values in that method.
227      * 
228      * <p>
229      * If the function returns <code>null</code>, there are no option labels
230      * available.
231      * <p>
232      * This list must be in the same sequence as the <code>getOptionValues()</code>
233      * method. I.e. for each index i in <code>getOptionLabels</code>, i in
234      * <code>getOptionValues()</code> should be the associated value.
235      * 
236      * <p>
237      * For example, if an attribute can have the value male, female, unknown,
238      * this list can return (for dutch)
239      * <code>new String[] { "Man", "Vrouw", "Onbekend" }</code>.
240      * 
241      * @return A list values
242      */
243     public String  [] getOptionLabels();
244 
245     /**
246      * Validate an attribute in <code>String</code> form.
247      * 
248      * An attribute might be further constrained in value. This method will
249      * attempt to validate the attribute according to these constraints. It can
250      * return three different values:
251      * 
252      * <pre>
253      *  null           No validation present
254      *  ""             No problems detected
255      *  "..."          A localized description of why the value is wrong
256      * </pre>
257      * 
258      * @param value The value before turning it into the basic data type
259      * @return <code>null</code>, "", or another string
260      */
261     public String   validate(String   value);
262 
263     /**
264      * Return a default for this attribute.
265      * 
266      * The object must be of the appropriate type as defined by the cardinality
267      * and <code>getType()</code>. The return type is a list of <code>String</code>
268      * objects that can be converted to the appropriate type. The cardinality of
269      * the return array must follow the absolute cardinality of this type. E.g.
270      * if the cardinality = 0, the array must contain 1 element. If the
271      * cardinality is 1, it must contain 0 or 1 elements. If it is -5, it must
272      * contain from 0 to max 5 elements. Note that the special case of a 0
273      * cardinality, meaning a single value, does not allow arrays or vectors of
274      * 0 elements.
275      * 
276      * @return Return a default value or <code>null</code> if no default exists.
277      */
278     public String  [] getDefaultValue();
279 }
280
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags