org.osgi.service.wireadmin.WireAdmin Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.osgi.service.wireadmin;

import java.util.Dictionary;

import org.osgi.framework.InvalidSyntaxException;

/**
 * Wire Administration service.
 * 
 * 
 * This service can be used to create Wire objects connecting a
 * Producer service and a Consumer service. Wire objects also have
 * wire properties that may be specified when a Wire object is
 * created. The Producer and Consumer services may use the Wire
 * object's properties to manage or control their interaction. The use of
 * Wire object's properties by a Producer or Consumer services is
 * optional.
 * 
 * 

 * Security Considerations. A bundle must have
 * ServicePermission[WireAdmin,GET] to get the Wire Admin service to
 * create, modify, find, and delete Wire objects.
 * 
 * @version $Revision: 5673 $
 */
public interface WireAdmin {
	/**
	 * Create a new Wire object that connects a Producer service to a
	 * Consumer service.
	 * 
	 * The Producer service and Consumer service do not have to be registered
	 * when the Wire object is created.
	 * 
	 * 

	 * The Wire configuration data must be persistently stored. All
	 * Wire connections are reestablished when the WireAdmin
	 * service is registered. A Wire can be permanently removed by
	 * using the {@link #deleteWire} method.
	 * 
	 * 

	 * The Wire object's properties must have case insensitive
	 * String objects as keys (like the Framework). However, the case
	 * of the key must be preserved.
	 * 
	 * 

	 * The WireAdmin service must automatically add the following
	 * Wire properties:
	 * 

	 * {@link WireConstants#WIREADMIN_PID} set to the value of the
	 * Wire object's persistent identity (PID). This value is
	 * generated by the Wire Admin service when a Wire object is
	 * created.
	 * {@link WireConstants#WIREADMIN_PRODUCER_PID} set to the value of
	 * Producer service's PID.
	 * {@link WireConstants#WIREADMIN_CONSUMER_PID} set to the value of
	 * Consumer service's PID.
	 * 
	 * If the properties argument already contains any of these keys,
	 * then the supplied values are replaced with the values assigned by the
	 * Wire Admin service.
	 * 
	 * 
	 * The Wire Admin service must broadcast a WireAdminEvent of type
	 * {@link WireAdminEvent#WIRE_CREATED} after the new Wire object
	 * becomes available from {@link #getWires}.
	 * 
	 * @param producerPID The service.pid of the Producer service to
	 *        be connected to the Wire object.
	 * @param consumerPID The service.pid of the Consumer service to
	 *        be connected to the Wire object.
	 * @param properties The Wire object's properties. This argument
	 *        may be null if the caller does not wish to define any
	 *        Wire object's properties.
	 * @return The Wire object for this connection.
	 * 
	 * @throws java.lang.IllegalArgumentException If properties
	 *         contains invalid wire types or case variants of the same key
	 *         name.
	 */
	public Wire createWire(String producerPID, String consumerPID,
			Dictionary properties);

	/**
	 * Delete a Wire object.
	 * 
	 * 

	 * The Wire object representing a connection between a Producer
	 * service and a Consumer service must be removed. The persistently stored
	 * configuration data for the Wire object must destroyed. The
	 * Wire object's method {@link Wire#isValid} will return
	 * false after it is deleted.
	 * 
	 * 

	 * The Wire Admin service must broadcast a WireAdminEvent of type
	 * {@link WireAdminEvent#WIRE_DELETED} after the Wire object
	 * becomes invalid.
	 * 
	 * @param wire The Wire object which is to be deleted.
	 */
	public void deleteWire(Wire wire);

	/**
	 * Update the properties of a Wire object.
	 * 
	 * The persistently stored configuration data for the Wire object
	 * is updated with the new properties and then the Consumer and Producer
	 * services will be called at the respective
	 * {@link Consumer#producersConnected} and
	 * {@link Producer#consumersConnected} methods.
	 * 
	 * 

	 * The Wire Admin service must broadcast a WireAdminEvent of type
	 * {@link WireAdminEvent#WIRE_UPDATED} after the updated properties are
	 * available from the Wire object.
	 * 
	 * @param wire The Wire object which is to be updated.
	 * @param properties The new Wire object's properties or
	 *        null if no properties are required.
	 * 
	 * @throws java.lang.IllegalArgumentException If properties
	 *         contains invalid wire types or case variants of the same key
	 *         name.
	 */
	public void updateWire(Wire wire, Dictionary properties);

	/**
	 * Return the Wire objects that match the given filter.
	 * 
	 * 

	 * The list of available Wire objects is matched against the
	 * specified filter.Wire objects which match the
	 * filter must be returned. These Wire objects are not
	 * necessarily connected. The Wire Admin service should not return invalid
	 * Wire objects, but it is possible that a Wire object
	 * is deleted after it was placed in the list.
	 * 
	 * 
	 * The filter matches against the Wire object's properties
	 * including {@link WireConstants#WIREADMIN_PRODUCER_PID},
	 * {@link WireConstants#WIREADMIN_CONSUMER_PID} and
	 * {@link WireConstants#WIREADMIN_PID}.
	 * 
	 * @param filter Filter string to select Wire objects or
	 *        null to select all Wire objects.
	 * @return An array of Wire objects which match the
	 *         filter or null if no Wire
	 *         objects match the filter.
	 * @throws org.osgi.framework.InvalidSyntaxException If the specified
	 *         filter has an invalid syntax.
	 * @see org.osgi.framework.Filter
	 */
	public Wire[] getWires(String filter) throws InvalidSyntaxException;
}