WireAdmin


1   /*
2    * $Header: /cvshome/build/org.osgi.service.wireadmin/src/org/osgi/service/wireadmin/WireAdmin.java,v 1.11 2006/07/12 21:22:14 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  import org.osgi.framework.InvalidSyntaxException;
23  
24  /**
25   * Wire Administration service.
26   * 
27   * <p>
28   * This service can be used to create <code>Wire</code> objects connecting a
29   * Producer service and a Consumer service. <code>Wire</code> objects also have
30   * wire properties that may be specified when a <code>Wire</code> object is
31   * created. The Producer and Consumer services may use the <code>Wire</code>
32   * object's properties to manage or control their interaction. The use of
33   * <code>Wire</code> object's properties by a Producer or Consumer services is
34   * optional.
35   * 
36   * <p>
37   * Security Considerations. A bundle must have
38   * <code>ServicePermission[WireAdmin,GET]</code> to get the Wire Admin service to
39   * create, modify, find, and delete <code>Wire</code> objects.
40   * 
41   * @version $Revision: 1.11 $
42   */
43  public interface WireAdmin {
44      /**
45       * Create a new <code>Wire</code> object that connects a Producer service to a
46       * Consumer service.
47       * 
48       * The Producer service and Consumer service do not have to be registered
49       * when the <code>Wire</code> object is created.
50       * 
51       * <p>
52       * The <code>Wire</code> configuration data must be persistently stored. All
53       * <code>Wire</code> connections are reestablished when the <code>WireAdmin</code>
54       * service is registered. A <code>Wire</code> can be permanently removed by
55       * using the {@link #deleteWire} method.
56       * 
57       * <p>
58       * The <code>Wire</code> object's properties must have case insensitive
59       * <code>String</code> objects as keys (like the Framework). However, the case
60       * of the key must be preserved.
61       * 
62       * <p>
63       * The <code>WireAdmin</code> service must automatically add the following
64       * <code>Wire</code> properties:
65       * <ul>
66       * <li>{@link WireConstants#WIREADMIN_PID} set to the value of the
67       * <code>Wire</code> object's persistent identity (PID). This value is
68       * generated by the Wire Admin service when a <code>Wire</code> object is
69       * created.</li>
70       * <li>{@link WireConstants#WIREADMIN_PRODUCER_PID} set to the value of
71       * Producer service's PID.</li>
72       * <li>{@link WireConstants#WIREADMIN_CONSUMER_PID} set to the value of
73       * Consumer service's PID.</li>
74       * </ul>
75       * If the <code>properties</code> argument already contains any of these keys,
76       * then the supplied values are replaced with the values assigned by the
77       * Wire Admin service.
78       * 
79       * <p>
80       * The Wire Admin service must broadcast a <code>WireAdminEvent</code> of type
81       * {@link WireAdminEvent#WIRE_CREATED} after the new <code>Wire</code> object
82       * becomes available from {@link #getWires}.
83       * 
84       * @param producerPID The <code>service.pid</code> of the Producer service to
85       *        be connected to the <code>Wire</code> object.
86       * @param consumerPID The <code>service.pid</code> of the Consumer service to
87       *        be connected to the <code>Wire</code> object.
88       * @param properties The <code>Wire</code> object's properties. This argument
89       *        may be <code>null</code> if the caller does not wish to define any
90       *        <code>Wire</code> object's properties.
91       * @return The <code>Wire</code> object for this connection.
92       * 
93       * @throws java.lang.IllegalArgumentException If <code>properties</code>
94       *         contains invalid wire types or case variants of the same key
95       *         name.
96       */
97      public Wire createWire(String   producerPID, String   consumerPID,
98              Dictionary   properties);
99  
100     /**
101      * Delete a <code>Wire</code> object.
102      * 
103      * <p>
104      * The <code>Wire</code> object representing a connection between a Producer
105      * service and a Consumer service must be removed. The persistently stored
106      * configuration data for the <code>Wire</code> object must destroyed. The
107      * <code>Wire</code> object's method {@link Wire#isValid} will return
108      * <code>false</code> after it is deleted.
109      * 
110      * <p>
111      * The Wire Admin service must broadcast a <code>WireAdminEvent</code> of type
112      * {@link WireAdminEvent#WIRE_DELETED} after the <code>Wire</code> object
113      * becomes invalid.
114      * 
115      * @param wire The <code>Wire</code> object which is to be deleted.
116      */
117     public void deleteWire(Wire wire);
118 
119     /**
120      * Update the properties of a <code>Wire</code> object.
121      * 
122      * The persistently stored configuration data for the <code>Wire</code> object
123      * is updated with the new properties and then the Consumer and Producer
124      * services will be called at the respective
125      * {@link Consumer#producersConnected} and
126      * {@link Producer#consumersConnected} methods.
127      * 
128      * <p>
129      * The Wire Admin service must broadcast a <code>WireAdminEvent</code> of type
130      * {@link WireAdminEvent#WIRE_UPDATED} after the updated properties are
131      * available from the <code>Wire</code> object.
132      * 
133      * @param wire The <code>Wire</code> object which is to be updated.
134      * @param properties The new <code>Wire</code> object's properties or
135      *        <code>null</code> if no properties are required.
136      * 
137      * @throws java.lang.IllegalArgumentException If <code>properties</code>
138      *         contains invalid wire types or case variants of the same key
139      *         name.
140      */
141     public void updateWire(Wire wire, Dictionary   properties);
142 
143     /**
144      * Return the <code>Wire</code> objects that match the given <code>filter</code>.
145      * 
146      * <p>
147      * The list of available <code>Wire</code> objects is matched against the
148      * specified <code>filter</code>.<code>Wire</code> objects which match the
149      * <code>filter</code> must be returned. These <code>Wire</code> objects are not
150      * necessarily connected. The Wire Admin service should not return invalid
151      * <code>Wire</code> objects, but it is possible that a <code>Wire</code> object
152      * is deleted after it was placed in the list.
153      * 
154      * <p>
155      * The filter matches against the <code>Wire</code> object's properties
156      * including {@link WireConstants#WIREADMIN_PRODUCER_PID},
157      * {@link WireConstants#WIREADMIN_CONSUMER_PID} and
158      * {@link WireConstants#WIREADMIN_PID}.
159      * 
160      * @param filter Filter string to select <code>Wire</code> objects or
161      *        <code>null</code> to select all <code>Wire</code> objects.
162      * @return An array of <code>Wire</code> objects which match the
163      *         <code>filter</code> or <code>null</code> if no <code>Wire</code>
164      *         objects match the <code>filter</code>.
165      * @throws org.osgi.framework.InvalidSyntaxException If the specified
166      *         <code>filter</code> has an invalid syntax.
167      * @see org.osgi.framework.Filter
168      */
169     public Wire[] getWires(String   filter) throws InvalidSyntaxException;
170 }
171
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags