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 import java.util.Dictionary;
019
020 import org.osgi.framework.InvalidSyntaxException;
021
022 /**
023 * Wire Administration service.
024 *
025 * <p>
026 * This service can be used to create <code>Wire</code> objects connecting a
027 * Producer service and a Consumer service. <code>Wire</code> objects also have
028 * wire properties that may be specified when a <code>Wire</code> object is
029 * created. The Producer and Consumer services may use the <code>Wire</code>
030 * object's properties to manage or control their interaction. The use of
031 * <code>Wire</code> object's properties by a Producer or Consumer services is
032 * optional.
033 *
034 * <p>
035 * Security Considerations. A bundle must have
036 * <code>ServicePermission[WireAdmin,GET]</code> to get the Wire Admin service to
037 * create, modify, find, and delete <code>Wire</code> objects.
038 *
039 * @version $Revision: 5673 $
040 */
041 public interface WireAdmin {
042 /**
043 * Create a new <code>Wire</code> object that connects a Producer service to a
044 * Consumer service.
045 *
046 * The Producer service and Consumer service do not have to be registered
047 * when the <code>Wire</code> object is created.
048 *
049 * <p>
050 * The <code>Wire</code> configuration data must be persistently stored. All
051 * <code>Wire</code> connections are reestablished when the <code>WireAdmin</code>
052 * service is registered. A <code>Wire</code> can be permanently removed by
053 * using the {@link #deleteWire} method.
054 *
055 * <p>
056 * The <code>Wire</code> object's properties must have case insensitive
057 * <code>String</code> objects as keys (like the Framework). However, the case
058 * of the key must be preserved.
059 *
060 * <p>
061 * The <code>WireAdmin</code> service must automatically add the following
062 * <code>Wire</code> properties:
063 * <ul>
064 * <li>{@link WireConstants#WIREADMIN_PID} set to the value of the
065 * <code>Wire</code> object's persistent identity (PID). This value is
066 * generated by the Wire Admin service when a <code>Wire</code> object is
067 * created.</li>
068 * <li>{@link WireConstants#WIREADMIN_PRODUCER_PID} set to the value of
069 * Producer service's PID.</li>
070 * <li>{@link WireConstants#WIREADMIN_CONSUMER_PID} set to the value of
071 * Consumer service's PID.</li>
072 * </ul>
073 * If the <code>properties</code> argument already contains any of these keys,
074 * then the supplied values are replaced with the values assigned by the
075 * Wire Admin service.
076 *
077 * <p>
078 * The Wire Admin service must broadcast a <code>WireAdminEvent</code> of type
079 * {@link WireAdminEvent#WIRE_CREATED} after the new <code>Wire</code> object
080 * becomes available from {@link #getWires}.
081 *
082 * @param producerPID The <code>service.pid</code> of the Producer service to
083 * be connected to the <code>Wire</code> object.
084 * @param consumerPID The <code>service.pid</code> of the Consumer service to
085 * be connected to the <code>Wire</code> object.
086 * @param properties The <code>Wire</code> object's properties. This argument
087 * may be <code>null</code> if the caller does not wish to define any
088 * <code>Wire</code> object's properties.
089 * @return The <code>Wire</code> object for this connection.
090 *
091 * @throws java.lang.IllegalArgumentException If <code>properties</code>
092 * contains invalid wire types or case variants of the same key
093 * name.
094 */
095 public Wire createWire(String producerPID, String consumerPID,
096 Dictionary properties);
097
098 /**
099 * Delete a <code>Wire</code> object.
100 *
101 * <p>
102 * The <code>Wire</code> object representing a connection between a Producer
103 * service and a Consumer service must be removed. The persistently stored
104 * configuration data for the <code>Wire</code> object must destroyed. The
105 * <code>Wire</code> object's method {@link Wire#isValid} will return
106 * <code>false</code> after it is deleted.
107 *
108 * <p>
109 * The Wire Admin service must broadcast a <code>WireAdminEvent</code> of type
110 * {@link WireAdminEvent#WIRE_DELETED} after the <code>Wire</code> object
111 * becomes invalid.
112 *
113 * @param wire The <code>Wire</code> object which is to be deleted.
114 */
115 public void deleteWire(Wire wire);
116
117 /**
118 * Update the properties of a <code>Wire</code> object.
119 *
120 * The persistently stored configuration data for the <code>Wire</code> object
121 * is updated with the new properties and then the Consumer and Producer
122 * services will be called at the respective
123 * {@link Consumer#producersConnected} and
124 * {@link Producer#consumersConnected} methods.
125 *
126 * <p>
127 * The Wire Admin service must broadcast a <code>WireAdminEvent</code> of type
128 * {@link WireAdminEvent#WIRE_UPDATED} after the updated properties are
129 * available from the <code>Wire</code> object.
130 *
131 * @param wire The <code>Wire</code> object which is to be updated.
132 * @param properties The new <code>Wire</code> object's properties or
133 * <code>null</code> if no properties are required.
134 *
135 * @throws java.lang.IllegalArgumentException If <code>properties</code>
136 * contains invalid wire types or case variants of the same key
137 * name.
138 */
139 public void updateWire(Wire wire, Dictionary properties);
140
141 /**
142 * Return the <code>Wire</code> objects that match the given <code>filter</code>.
143 *
144 * <p>
145 * The list of available <code>Wire</code> objects is matched against the
146 * specified <code>filter</code>.<code>Wire</code> objects which match the
147 * <code>filter</code> must be returned. These <code>Wire</code> objects are not
148 * necessarily connected. The Wire Admin service should not return invalid
149 * <code>Wire</code> objects, but it is possible that a <code>Wire</code> object
150 * is deleted after it was placed in the list.
151 *
152 * <p>
153 * The filter matches against the <code>Wire</code> object's properties
154 * including {@link WireConstants#WIREADMIN_PRODUCER_PID},
155 * {@link WireConstants#WIREADMIN_CONSUMER_PID} and
156 * {@link WireConstants#WIREADMIN_PID}.
157 *
158 * @param filter Filter string to select <code>Wire</code> objects or
159 * <code>null</code> to select all <code>Wire</code> objects.
160 * @return An array of <code>Wire</code> objects which match the
161 * <code>filter</code> or <code>null</code> if no <code>Wire</code>
162 * objects match the <code>filter</code>.
163 * @throws org.osgi.framework.InvalidSyntaxException If the specified
164 * <code>filter</code> has an invalid syntax.
165 * @see org.osgi.framework.Filter
166 */
167 public Wire[] getWires(String filter) throws InvalidSyntaxException;
168 }