001 /*
002 * Copyright (c) OSGi Alliance (2002, 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.wireadmin;
017
018 /**
019 * Defines standard names for <code>Wire</code> properties, wire filter
020 * attributes, Consumer and Producer service properties.
021 *
022 * @version $Revision: 5673 $
023 */
024 public interface WireConstants {
025 /**
026 * <code>Wire</code> property key (named <code>wireadmin.pid</code>) specifying
027 * the persistent identity (PID) of this <code>Wire</code> object.
028 *
029 * <p>
030 * Each <code>Wire</code> object has a PID to allow unique and persistent
031 * identification of a specific <code>Wire</code> object. The PID must be
032 * generated by the {@link WireAdmin} service when the <code>Wire</code>
033 * object is created.
034 *
035 * <p>
036 * This wire property is automatically set by the Wire Admin service. The
037 * value of the property must be of type <code>String</code>.
038 */
039 public final static String WIREADMIN_PID = "wireadmin.pid";
040 /**
041 * A service registration property for a Producer service that is composite.
042 * It contains the names of the composite Consumer services it can
043 * inter-operate with. Inter-operability exists when any name in this array
044 * matches any name in the array set by the Consumer service. The type of
045 * this property must be <code>String[]</code>.
046 */
047 public final static String WIREADMIN_PRODUCER_COMPOSITE = "wireadmin.producer.composite";
048 /**
049 * A service registration property for a Consumer service that is composite.
050 * It contains the names of the composite Producer services it can cooperate
051 * with. Inter-operability exists when any name in this array matches any
052 * name in the array set by the Producer service. The type of this property
053 * must be <code>String[]</code>.
054 */
055 public final static String WIREADMIN_CONSUMER_COMPOSITE = "wireadmin.consumer.composite";
056 /**
057 * Service registration property key (named
058 * <code>wireadmin.producer.scope</code>) specifying a list of names that may
059 * be used to define the scope of this <code>Wire</code> object. A Producer
060 * service should set this service property when it can produce more than
061 * one kind of value. This property is only used during registration,
062 * modifying the property must not have any effect of the <code>Wire</code>
063 * object's scope. Each name in the given list mist have
064 * <code>WirePermission[name,PRODUCE]</code> or else is ignored. The type of
065 * this service registration property must be <code>String[]</code>.
066 *
067 * @see Wire#getScope
068 * @see #WIREADMIN_CONSUMER_SCOPE
069 */
070 public final static String WIREADMIN_PRODUCER_SCOPE = "wireadmin.producer.scope";
071 /**
072 * Service registration property key (named
073 * <code>wireadmin.consumer.scope</code>) specifying a list of names that may
074 * be used to define the scope of this <code>Wire</code> object. A
075 * <code>Consumer</code> service should set this service property when it can
076 * produce more than one kind of value. This property is only used during
077 * registration, modifying the property must not have any effect of the
078 * <code>Wire</code> object's scope. Each name in the given list mist have
079 * <code>WirePermission[name,CONSUME]</code> or else is ignored. The type of this
080 * service registration property must be <code>String[]</code>.
081 *
082 * @see Wire#getScope
083 * @see #WIREADMIN_PRODUCER_SCOPE
084 */
085 public final static String WIREADMIN_CONSUMER_SCOPE = "wireadmin.consumer.scope";
086 /**
087 * Matches all scope names.
088 */
089 public final static String WIREADMIN_SCOPE_ALL[] = {"*"};
090 /**
091 * <code>Wire</code> property key (named <code>wireadmin.producer.pid</code>)
092 * specifying the <code>service.pid</code> of the associated Producer service.
093 *
094 * <p>
095 * This wire property is automatically set by the WireAdmin service. The
096 * value of the property must be of type <code>String</code>.
097 */
098 public final static String WIREADMIN_PRODUCER_PID = "wireadmin.producer.pid";
099 /**
100 * <code>Wire</code> property key (named <code>wireadmin.consumer.pid</code>)
101 * specifying the <code>service.pid</code> of the associated Consumer service.
102 *
103 * <p>
104 * This wire property is automatically set by the Wire Admin service. The
105 * value of the property must be of type <code>String</code>.
106 */
107 public final static String WIREADMIN_CONSUMER_PID = "wireadmin.consumer.pid";
108 /**
109 * <code>Wire</code> property key (named <code>wireadmin.filter</code>)
110 * specifying a filter used to control the delivery rate of data between the
111 * Producer and the Consumer service.
112 *
113 * <p>
114 * This property should contain a filter as described in the <code>Filter</code>
115 * class. The filter can be used to specify when an updated value from the
116 * Producer service should be delivered to the Consumer service. In many
117 * cases the Consumer service does not need to receive the data with the
118 * same rate that the Producer service can generate data. This property can
119 * be used to control the delivery rate.
120 * <p>
121 * The filter can use a number of pre-defined attributes that can be used to
122 * control the delivery of new data values. If the filter produces a match
123 * upon the wire filter attributes, the Consumer service should be notifed
124 * of the updated data value.
125 * <p>
126 * If the Producer service was registered with the
127 * {@link #WIREADMIN_PRODUCER_FILTERS} service property indicating that the
128 * Producer service will perform the data filtering then the <code>Wire</code>
129 * object will not perform data filtering. Otherwise, the <code>Wire</code>
130 * object must perform basic filtering. Basic filtering includes supporting
131 * the following standard wire filter attributes:
132 * <ul>
133 * <li>{@link #WIREVALUE_CURRENT}- Current value
134 * <li>{@link #WIREVALUE_PREVIOUS}- Previous value
135 * <li>{@link #WIREVALUE_DELTA_ABSOLUTE}- Absolute delta
136 * <li>{@link #WIREVALUE_DELTA_RELATIVE}- Relative delta
137 * <li>{@link #WIREVALUE_ELAPSED}- Elapsed time
138 * </ul>
139 *
140 * @see org.osgi.framework.Filter
141 */
142 public final static String WIREADMIN_FILTER = "wireadmin.filter";
143 /* Wire filter attribute names. */
144 /**
145 * <code>Wire</code> object's filter attribute (named
146 * <code>wirevalue.current</code>) representing the current value.
147 */
148 public final static String WIREVALUE_CURRENT = "wirevalue.current";
149 /**
150 * <code>Wire</code> object's filter attribute (named
151 * <code>wirevalue.previous</code>) representing the previous value.
152 */
153 public final static String WIREVALUE_PREVIOUS = "wirevalue.previous";
154 /**
155 * <code>Wire</code> object's filter attribute (named
156 * <code>wirevalue.delta.absolute</code>) representing the absolute delta.
157 * The absolute (always positive) difference between the last update and the
158 * current value (only when numeric). This attribute must not be used when
159 * the values are not numeric.
160 */
161 public final static String WIREVALUE_DELTA_ABSOLUTE = "wirevalue.delta.absolute";
162 /**
163 * <code>Wire</code> object's filter attribute (named
164 * <code>wirevalue.delta.relative</code>) representing the relative delta.
165 * The relative difference is |<code>previous</code>-<code>current</code> |/|
166 * <code>current</code>| (only when numeric). This attribute must not be used
167 * when the values are not numeric.
168 */
169 public final static String WIREVALUE_DELTA_RELATIVE = "wirevalue.delta.relative";
170 /**
171 * <code>Wire</code> object's filter attribute (named
172 * <code>wirevalue.elapsed</code>) representing the elapsed time, in ms,
173 * between this filter evaluation and the last update of the
174 * <code>Consumer</code> service.
175 */
176 public final static String WIREVALUE_ELAPSED = "wirevalue.elapsed";
177 /* Service registration property key names. */
178 /**
179 * Service Registration property (named <code>wireadmin.producer.filters</code>).
180 * A <code>Producer</code> service registered with this property indicates to
181 * the Wire Admin service that the Producer service implements at least the
182 * filtering as described for the {@link #WIREADMIN_FILTER} property. If the
183 * Producer service is not registered with this property, the <code>Wire</code>
184 * object must perform the basic filtering as described in
185 * {@link #WIREADMIN_FILTER}.
186 *
187 * <p>
188 * The type of the property value is not relevant. Only its presence is
189 * relevant.
190 */
191 public final static String WIREADMIN_PRODUCER_FILTERS = "wireadmin.producer.filters";
192 /**
193 * Service Registration property (named <code>wireadmin.consumer.flavors</code>)
194 * specifying the list of data types understood by this Consumer service.
195 *
196 * <p>
197 * The Consumer service object must be registered with this service
198 * property. The list must be in the order of preference with the first type
199 * being the most preferred. The value of the property must be of type
200 * <code>Class[]</code>.
201 */
202 public final static String WIREADMIN_CONSUMER_FLAVORS = "wireadmin.consumer.flavors";
203 /**
204 * Service Registration property (named <code>wireadmin.producer.flavors</code>)
205 * specifying the list of data types available from this Producer service.
206 *
207 * <p>
208 * The Producer service object should be registered with this service
209 * property.
210 *
211 * <p>
212 * The value of the property must be of type <code>Class[]</code>.
213 */
214 public final static String WIREADMIN_PRODUCER_FLAVORS = "wireadmin.producer.flavors";
215 /**
216 * Service Registration property (named <code>wireadmin.events</code>)
217 * specifying the <code>WireAdminEvent</code> type of interest to a Wire Admin
218 * Listener service. The value of the property is a bitwise OR of all the
219 * <code>WireAdminEvent</code> types the Wire Admin Listener service wishes to
220 * receive and must be of type <code>Integer</code>.
221 *
222 * @see WireAdminEvent
223 */
224 public final static String WIREADMIN_EVENTS = "wireadmin.events";
225 }