Wire


1   /*
2    * $Header: /cvshome/build/org.osgi.service.wireadmin/src/org/osgi/service/wireadmin/Wire.java,v 1.10 2006/07/11 00:54:10 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.wireadmin;
19  
20  import java.util.Dictionary  ;
21  
22  /**
23   * A connection between a Producer service and a Consumer service.
24   * 
25   * <p>
26   * A <code>Wire</code> object connects a Producer service to a Consumer service.
27   * Both the Producer and Consumer services are identified by their unique
28   * <code>service.pid</code> values. The Producer and Consumer services may
29   * communicate with each other via <code>Wire</code> objects that connect them.
30   * The Producer service may send updated values to the Consumer service by
31   * calling the {@link #update} method. The Consumer service may request an
32   * updated value from the Producer service by calling the {@link #poll} method.
33   * 
34   * <p>
35   * A Producer service and a Consumer service may be connected through multiple
36   * <code>Wire</code> objects.
37   * 
38   * <p>
39   * Security Considerations. <code>Wire</code> objects are available to Producer
40   * and Consumer services connected to a given <code>Wire</code> object and to
41   * bundles which can access the <code>WireAdmin</code> service. A bundle must have
42   * <code>ServicePermission[WireAdmin,GET]</code> to get the <code>WireAdmin</code>
43   * service to access all <code>Wire</code> objects. A bundle registering a
44   * Producer service or a Consumer service must have the appropriate
45   * <code>ServicePermission[Consumer|Producer,REGISTER]</code> to register the
46   * service and will be passed <code>Wire</code> objects when the service object's
47   * <code>consumersConnected</code> or <code>producersConnected</code> method is
48   * called.
49   * 
50   * <p>
51   * Scope. Each Wire object can have a scope set with the <code>setScope</code>
52   * method. This method should be called by a Consumer service when it assumes a
53   * Producer service that is composite (supports multiple information items). The
54   * names in the scope must be verified by the <code>Wire</code> object before it
55   * is used in communication. The semantics of the names depend on the Producer
56   * service and must not be interpreted by the Wire Admin service.
57   * 
58   * @version $Revision: 1.10 $
59   */
60  public interface Wire {
61      /**
62       * Return the state of this <code>Wire</code> object.
63       * 
64       * <p>
65       * A connected <code>Wire</code> must always be disconnected before becoming
66       * invalid.
67       * 
68       * @return <code>false</code> if this <code>Wire</code> object is invalid
69       *         because it has been deleted via {@link WireAdmin#deleteWire};
70       *         <code>true</code> otherwise.
71       */
72      public boolean isValid();
73  
74      /**
75       * Return the connection state of this <code>Wire</code> object.
76       * 
77       * <p>
78       * A <code>Wire</code> is connected after the Wire Admin service receives
79       * notification that the Producer service and the Consumer service for this
80       * <code>Wire</code> object are both registered. This method will return
81       * <code>true</code> prior to notifying the Producer and Consumer services via
82       * calls to their respective <code>consumersConnected</code> and
83       * <code>producersConnected</code> methods.
84       * <p>
85       * A <code>WireAdminEvent</code> of type {@link WireAdminEvent#WIRE_CONNECTED}
86       * must be broadcast by the Wire Admin service when the <code>Wire</code>
87       * becomes connected.
88       * 
89       * <p>
90       * A <code>Wire</code> object is disconnected when either the Consumer or
91       * Producer service is unregistered or the <code>Wire</code> object is
92       * deleted.
93       * <p>
94       * A <code>WireAdminEvent</code> of type
95       * {@link WireAdminEvent#WIRE_DISCONNECTED} must be broadcast by the Wire
96       * Admin service when the <code>Wire</code> becomes disconnected.
97       * 
98       * @return <code>true</code> if both the Producer and Consumer for this
99       *         <code>Wire</code> object are connected to the <code>Wire</code>
100      *         object; <code>false</code> otherwise.
101      */
102     public boolean isConnected();
103 
104     /**
105      * Return the list of data types understood by the Consumer service
106      * connected to this <code>Wire</code> object. Note that subclasses of the
107      * classes in this list are acceptable data types as well.
108      * 
109      * <p>
110      * The list is the value of the
111      * {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} service property of the
112      * Consumer service object connected to this object. If no such property was
113      * registered or the type of the property value is not <code>Class[]</code>,
114      * this method must return <code>null</code>.
115      * 
116      * @return An array containing the list of classes understood by the
117      *         Consumer service or <code>null</code> if the <code>Wire</code> is not
118      *         connected, or the consumer did not register a
119      *         {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} property or the
120      *         value of the property is not of type <code>Class[]</code>.
121      */
122     public Class  [] getFlavors();
123 
124     /**
125      * Update the value.
126      * 
127      * <p>
128      * This methods is called by the Producer service to notify the Consumer
129      * service connected to this <code>Wire</code> object of an updated value.
130      * <p>
131      * If the properties of this <code>Wire</code> object contain a
132      * {@link WireConstants#WIREADMIN_FILTER} property, then filtering is
133      * performed. If the Producer service connected to this <code>Wire</code>
134      * object was registered with the service property
135      * {@link WireConstants#WIREADMIN_PRODUCER_FILTERS}, the Producer service
136      * will perform the filtering according to the rules specified for the
137      * filter. Otherwise, this <code>Wire</code> object will perform the filtering
138      * of the value.
139      * <p>
140      * If no filtering is done, or the filter indicates the updated value should
141      * be delivered to the Consumer service, then this <code>Wire</code> object
142      * must call the {@link Consumer#updated} method with the updated value. If
143      * this <code>Wire</code> object is not connected, then the Consumer service
144      * must not be called and the value is ignored.
145      * <p>
146      * If the value is an <code>Envelope</code> object, and the scope name is not
147      * permitted, then the <code>Wire</code> object must ignore this call and not
148      * transfer the object to the Consumer service.
149      * 
150      * <p>
151      * A <code>WireAdminEvent</code> of type {@link WireAdminEvent#WIRE_TRACE}
152      * must be broadcast by the Wire Admin service after the Consumer service
153      * has been successfully called.
154      * 
155      * @param value The updated value. The value should be an instance of one of
156      *        the types returned by {@link #getFlavors}.
157      * @see WireConstants#WIREADMIN_FILTER
158      */
159     public void update(Object   value);
160 
161     /**
162      * Poll for an updated value.
163      * 
164      * <p>
165      * This methods is normally called by the Consumer service to request an
166      * updated value from the Producer service connected to this <code>Wire</code>
167      * object. This <code>Wire</code> object will call the {@link Producer#polled}
168      * method to obtain an updated value. If this <code>Wire</code> object is not
169      * connected, then the Producer service must not be called.
170      * <p>
171      * 
172      * If this <code>Wire</code> object has a scope, then this method must return
173      * an array of <code>Envelope</code> objects. The objects returned must match
174      * the scope of this object. The <code>Wire</code> object must remove all
175      * <code>Envelope</code> objects with a scope name that is not in the
176      * <code>Wire</code> object's scope. Thus, the list of objects returned must
177      * only contain <code>Envelope</code> objects with a permitted scope name. If
178      * the array becomes empty, <code>null</code> must be returned.
179      * 
180      * <p>
181      * A <code>WireAdminEvent</code> of type {@link WireAdminEvent#WIRE_TRACE}
182      * must be broadcast by the Wire Admin service after the Producer service
183      * has been successfully called.
184      * 
185      * @return A value whose type should be one of the types returned by
186      *         {@link #getFlavors},<code>Envelope[]</code>, or <code>null</code>
187      *         if the <code>Wire</code> object is not connected, the Producer
188      *         service threw an exception, or the Producer service returned a
189      *         value which is not an instance of one of the types returned by
190      *         {@link #getFlavors}.
191      */
192     public Object   poll();
193 
194     /**
195      * Return the last value sent through this <code>Wire</code> object.
196      * 
197      * <p>
198      * The returned value is the most recent, valid value passed to the
199      * {@link #update} method or returned by the {@link #poll} method of this
200      * object. If filtering is performed by this <code>Wire</code> object, this
201      * methods returns the last value provided by the Producer service. This
202      * value may be an <code>Envelope[]</code> when the Producer service uses
203      * scoping. If the return value is an Envelope object (or array), it must be
204      * verified that the Consumer service has the proper WirePermission to see
205      * it.
206      * 
207      * @return The last value passed though this <code>Wire</code> object or
208      *         <code>null</code> if no valid values have been passed or the
209      *         Consumer service has no permission.
210      */
211     public Object   getLastValue();
212 
213     /**
214      * Return the wire properties for this <code>Wire</code> object.
215      * 
216      * @return The properties for this <code>Wire</code> object. The returned
217      *         <code>Dictionary</code> must be read only.
218      */
219     public Dictionary   getProperties();
220 
221     /**
222      * Return the calculated scope of this <code>Wire</code> object.
223      * 
224      * The purpose of the <code>Wire</code> object's scope is to allow a Producer
225      * and/or Consumer service to produce/consume different types over a single
226      * <code>Wire</code> object (this was deemed necessary for efficiency
227      * reasons). Both the Consumer service and the Producer service must set an
228      * array of scope names (their scope) with the service registration property
229      * <code>WIREADMIN_PRODUCER_SCOPE</code>, or
230      * <code>WIREADMIN_CONSUMER_SCOPE</code> when they can produce multiple types.
231      * If a Producer service can produce different types, it should set this
232      * property to the array of scope names it can produce, the Consumer service
233      * must set the array of scope names it can consume. The scope of a
234      * <code>Wire</code> object is defined as the intersection of permitted scope
235      * names of the Producer service and Consumer service.
236      * <p>
237      * If neither the Consumer, or the Producer service registers scope names
238      * with its service registration, then the <code>Wire</code> object's scope
239      * must be <code>null</code>.
240      * <p>
241      * The <code>Wire</code> object's scope must not change when a Producer or
242      * Consumer services modifies its scope.
243      * <p>
244      * A scope name is permitted for a Producer service when the registering
245      * bundle has <code>WirePermission[name,PRODUCE]</code>, and for a Consumer
246      * service when the registering bundle has <code>WirePermission[name,CONSUME]</code>.
247      * <p>
248      * If either Consumer service or Producer service has not set a
249      * <code>WIREADMIN_*_SCOPE</code> property, then the returned value must be
250      * <code>null</code>.
251      * <p>
252      * If the scope is set, the <code>Wire</code> object must enforce the scope
253      * names when <code>Envelope</code> objects are used as a parameter to update
254      * or returned from the <code>poll</code> method. The <code>Wire</code> object
255      * must then remove all <code>Envelope</code> objects with a scope name that
256      * is not permitted.
257      * 
258      * @return A list of permitted scope names or null if the Produce or
259      *         Consumer service has set no scope names.
260      */
261     public String  [] getScope();
262 
263     /**
264      * Return true if the given name is in this <code>Wire</code> object's scope.
265      * 
266      * @param name The scope name
267      * @return true if the name is listed in the permitted scope names
268      */
269     public boolean hasScope(String   name);
270 }
271
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags