UPnPStateVariable


1   /*
2    * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPStateVariable.java,v 1.8 2006/06/16 16:31:46 hargrave Exp $
3    *
4    * Copyright (c) OSGi Alliance (2002, 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.upnp;
19  
20  /**
21   * The meta-information of a UPnP state variable as declared in the device's
22   * service state table (SST).
23   * <p>
24   * Method calls to interact with a device (e.g. <code>UPnPAction.invoke(...);</code>)
25   * use this class to encapsulate meta information about the input and output
26   * arguments.
27   * <p>
28   * The actual values of the arguments are passed as Java objects. The mapping of
29   * types from UPnP data types to Java data types is described with the field
30   * definitions.
31   */
32  public interface UPnPStateVariable {
33      /**
34       * Unsigned 1 <code>Byte</code> int.
35       * <p>
36       * Mapped to an <code>Integer</code> object.
37       */
38      static final String   TYPE_UI1            = "ui1";
39      /**
40       * Unsigned 2 Byte int.
41       * <p>
42       * Mapped to <code>Integer</code> object.
43       */
44      static final String   TYPE_UI2            = "ui2";
45      /**
46       * Unsigned 4 Byte int.
47       * <p>
48       * Mapped to <code>Long</code> object.
49       */
50      static final String   TYPE_UI4            = "ui4";
51      /**
52       * 1 Byte int.
53       * <p>
54       * Mapped to <code>Integer</code> object.
55       */
56      static final String   TYPE_I1             = "i1";
57      /**
58       * 2 Byte int.
59       * <p>
60       * Mapped to <code>Integer</code> object.
61       */
62      static final String   TYPE_I2             = "i2";
63      /**
64       * 4 Byte int.
65       * <p>
66       * Must be between -2147483648 and 2147483647
67       * <p>
68       * Mapped to <code>Integer</code> object.
69       */
70      static final String   TYPE_I4             = "i4";
71      /**
72       * Integer number.
73       * <p>
74       * Mapped to <code>Integer</code> object.
75       */
76      static final String   TYPE_INT            = "int";
77      /**
78       * 4 Byte float.
79       * <p>
80       * Same format as float. Must be between 3.40282347E+38 to 1.17549435E-38.
81       * <p>
82       * Mapped to <code>Float</code> object.
83       */
84      static final String   TYPE_R4             = "r4";
85      /**
86       * 8 Byte float.
87       * <p>
88       * Same format as float. Must be between -1.79769313486232E308 and
89       * -4.94065645841247E-324 for negative values, and between
90       * 4.94065645841247E-324 and 1.79769313486232E308 for positive values, i.e.,
91       * IEEE 64-bit (8-Byte) double.
92       * <p>
93       * Mapped to <code>Double</code> object.
94       */
95      static final String   TYPE_R8             = "r8";
96      /**
97       * Same as r8.
98       * <p>
99       * Mapped to <code>Double</code> object.
100      */
101     static final String   TYPE_NUMBER         = "number";
102     /**
103      * Same as r8 but no more than 14 digits to the left of the decimal point
104      * and no more than 4 to the right.
105      * <p>
106      * Mapped to <code>Double</code> object.
107      */
108     static final String   TYPE_FIXED_14_4     = "fixed.14.4";
109     /**
110      * Floating-point number.
111      * <p>
112      * Mantissa (left of the decimal) and/or exponent may have a leading sign.
113      * Mantissa and/or exponent may have leading zeros. Decimal character in
114      * mantissa is a period, i.e., whole digits in mantissa separated from
115      * fractional digits by period. Mantissa separated from exponent by E. (No
116      * currency symbol.) (No grouping of digits in the mantissa, e.g., no
117      * commas.)
118      * <p>
119      * Mapped to <code>Float</code> object.
120      */
121     static final String   TYPE_FLOAT          = "float";
122     /**
123      * Unicode string.
124      * <p>
125      * One character long.
126      * <p>
127      * Mapped to <code>Character</code> object.
128      */
129     static final String   TYPE_CHAR           = "char";
130     /**
131      * Unicode string.
132      * <p>
133      * No limit on length.
134      * <p>
135      * Mapped to <code>String</code> object.
136      */
137     static final String   TYPE_STRING         = "string";
138     /**
139      * A calendar date.
140      * <p>
141      * Date in a subset of ISO 8601 format without time data.
142      * <p>
143      * See <a
144      * HREF="http://www.w3.org/TR/xmlschema-2/#date">http://www.w3.org/TR/xmlschema-2/#date
145      * </a>.
146      * <p>
147      * Mapped to <code>java.util.Date</code> object. Always 00:00 hours.
148      */
149     static final String   TYPE_DATE           = "date";
150     /**
151      * A specific instant of time.
152      * <p>
153      * Date in ISO 8601 format with optional time but no time zone.
154      * <p>
155      * See <a
156      * HREF="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#dateTime
157      * </a>.
158      * <p>
159      * Mapped to <code>java.util.Date</code> object using default time zone.
160      */
161     static final String   TYPE_DATETIME       = "dateTime";
162     /**
163      * A specific instant of time.
164      * <p>
165      * Date in ISO 8601 format with optional time and optional time zone.
166      * <p>
167      * See <a
168      * HREF="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#dateTime
169      * </a>.
170      * <p>
171      * Mapped to <code>java.util.Date</code> object adjusted to default time zone.
172      */
173     static final String   TYPE_DATETIME_TZ    = "dateTime.tz";
174     /**
175      * An instant of time that recurs every day.
176      * <p>
177      * Time in a subset of ISO 8601 format with no date and no time zone.
178      * <p>
179      * See <a
180      * HREF="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#time
181      * </a>.
182      * <p>
183      * Mapped to <code>Long</code>. Converted to milliseconds since midnight.
184      */
185     static final String   TYPE_TIME           = "time";
186     /**
187      * An instant of time that recurs every day.
188      * <p>
189      * Time in a subset of ISO 8601 format with optional time zone but no date.
190      * <p>
191      * See <a
192      * HREF="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#time
193      * </a>.
194      * <p>
195      * Mapped to <code>Long</code> object. Converted to milliseconds since
196      * midnight and adjusted to default time zone, wrapping at 0 and
197      * 24*60*60*1000.
198      */
199     static final String   TYPE_TIME_TZ        = "time.tz";
200     /**
201      * True or false.
202      * <p>
203      * Mapped to <code>Boolean</code> object.
204      */
205     static final String   TYPE_BOOLEAN        = "boolean";
206     /**
207      * MIME-style Base64 encoded binary BLOB.
208      * <p>
209      * Takes 3 Bytes, splits them into 4 parts, and maps each 6 bit piece to an
210      * octet. (3 octets are encoded as 4.) No limit on size.
211      * <p>
212      * Mapped to <code>byte[]</code> object. The Java byte array will hold the
213      * decoded content of the BLOB.
214      */
215     static final String   TYPE_BIN_BASE64     = "bin.base64";
216     /**
217      * Hexadecimal digits representing octets.
218      * <p>
219      * Treats each nibble as a hex digit and encodes as a separate Byte. (1
220      * octet is encoded as 2.) No limit on size.
221      * <p>
222      * Mapped to <code>byte[]</code> object. The Java byte array will hold the
223      * decoded content of the BLOB.
224      */
225     static final String   TYPE_BIN_HEX        = "bin.hex";
226     /**
227      * Universal Resource Identifier.
228      * <p>
229      * Mapped to <code>String</code> object.
230      */
231     static final String   TYPE_URI            = "uri";
232     /**
233      * Universally Unique ID.
234      * <p>
235      * Hexadecimal digits representing octets. Optional embedded hyphens are
236      * ignored.
237      * <p>
238      * Mapped to <code>String</code> object.
239      */
240     static final String   TYPE_UUID           = "uuid";
241 
242     /**
243      * Returns the variable name.
244      * 
245      * <ul>
246      * <li>All standard variables defined by a UPnP Forum working committee
247      * must not begin with <code>X_</code> nor <code>A_</code>.</li>
248      * <li>All non-standard variables specified by a UPnP vendor and added to a
249      * standard service must begin with <code>X_</code>.</li>
250      * </ul>
251      * 
252      * @return Name of state variable. Must not contain a hyphen character nor a
253      *         hash character. Should be &lt; 32 characters.
254      */
255     String   getName();
256 
257     /**
258      * Returns the Java class associated with the UPnP data type of this state
259      * variable.
260      * <P>
261      * Mapping between the UPnP data types and Java classes is performed
262      * according to the schema mentioned above.
263      * 
264      * <pre>
265      * 
266      *  Integer              ui1, ui2, i1, i2, i4, int
267      *  Long                 ui4, time, time.tz
268      *  Float                r4, float
269      *  Double               r8, number, fixed.14.4
270      *  Character            char
271      *  String               string, uri, uuid
272      *  Date                 date, dateTime, dateTime.tz
273      *  Boolean              boolean
274      *  byte[]               bin.base64, bin.hex
275      *  
276      * </pre>
277      * 
278      * @return A class object corresponding to the Java type of this argument.
279      */
280     Class   getJavaDataType();
281 
282     /**
283      * Returns the UPnP type of this state variable. Valid types are defined as
284      * constants.
285      * 
286      * @return The UPnP data type of this state variable, as defined in above
287      *         constants.
288      */
289     String   getUPnPDataType();
290 
291     /**
292      * Returns the default value, if defined.
293      * 
294      * @return The default value or <code>null</code> if not defined. The type of
295      *         the returned object can be determined by <code>getJavaDataType</code>.
296      */
297     Object   getDefaultValue();
298 
299     /**
300      * Returns the allowed values, if defined. Allowed values can be defined
301      * only for String types.
302      * 
303      * @return The allowed values or <code>null</code> if not defined. Should be
304      *         less than 32 characters.
305      */
306     String  [] getAllowedValues();
307 
308     /**
309      * Returns the minimum value, if defined. Minimum values can only be defined
310      * for numeric types.
311      * 
312      * @return The minimum value or <code>null</code> if not defined.
313      */
314     Number   getMinimum();
315 
316     /**
317      * Returns the maximum value, if defined. Maximum values can only be defined
318      * for numeric types.
319      * 
320      * @return The maximum value or <code>null</code> if not defined.
321      */
322     Number   getMaximum();
323 
324     /**
325      * Returns the size of an increment operation, if defined. Step sizes can be
326      * defined only for numeric types.
327      * 
328      * @return The increment size or null if not defined.
329      */
330     Number   getStep();
331 
332     /**
333      * Tells if this StateVariable can be used as an event source.
334      * 
335      * If the StateVariable is eventable, an event listener service can be
336      * registered to be notified when changes to the variable appear.
337      * 
338      * @return <code>true</code> if the <code>StateVariable</code> generates events,
339      *         <code>false</code> otherwise.
340      */
341     boolean sendsEvents();
342 }
343
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags