/*
 * Copyright (c) OSGi Alliance (2002, 2015). 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;

/**
 * A connection between a Producer service and a Consumer service.
 * 
 * <p>
 * A {@code Wire} object connects a Producer service to a Consumer service. Both
 * the Producer and Consumer services are identified by their unique
 * {@code service.pid} values. The Producer and Consumer services may
 * communicate with each other via {@code Wire} objects that connect them. The
 * Producer service may send updated values to the Consumer service by calling
 * the {@link #update(Object)} method. The Consumer service may request an
 * updated value from the Producer service by calling the {@link #poll()}
 * method.
 * 
 * <p>
 * A Producer service and a Consumer service may be connected through multiple
 * {@code Wire} objects.
 * 
 * <p>
 * Security Considerations. {@code Wire} objects are available to Producer and
 * Consumer services connected to a given {@code Wire} object and to bundles
 * which can access the {@code WireAdmin} service. A bundle must have
 * {@code ServicePermission[WireAdmin,GET]} to get the {@code WireAdmin} service
 * to access all {@code Wire} objects. A bundle registering a Producer service
 * or a Consumer service must have the appropriate
 * {@code ServicePermission[Consumer|Producer,REGISTER]} to register the service
 * and will be passed {@code Wire} objects when the service object's
 * {@code consumersConnected} or {@code producersConnected} method is called.
 * 
 * <p>
 * Scope. Each Wire object can have a scope set with the {@code setScope}
 * method. This method should be called by a Consumer service when it assumes a
 * Producer service that is composite (supports multiple information items). The
 * names in the scope must be verified by the {@code Wire} object before it is
 * used in communication. The semantics of the names depend on the Producer
 * service and must not be interpreted by the Wire Admin service.
 * 
 * @noimplement
 * @author $Id$
 */
public interface Wire {
	/**
	 * Return the state of this {@code Wire} object.
	 * 
	 * <p>
	 * A connected {@code Wire} must always be disconnected before becoming
	 * invalid.
	 * 
	 * @return {@code false} if this {@code Wire} object is invalid because it
	 *         has been deleted via {@link WireAdmin#deleteWire(Wire)};
	 *         {@code true} otherwise.
	 */
	public boolean isValid();

	/**
	 * Return the connection state of this {@code Wire} object.
	 * 
	 * <p>
	 * A {@code Wire} is connected after the Wire Admin service receives
	 * notification that the Producer service and the Consumer service for this
	 * {@code Wire} object are both registered. This method will return
	 * {@code true} prior to notifying the Producer and Consumer services via
	 * calls to their respective {@code consumersConnected} and
	 * {@code producersConnected} methods.
	 * <p>
	 * A {@code WireAdminEvent} of type {@link WireAdminEvent#WIRE_CONNECTED}
	 * must be broadcast by the Wire Admin service when the {@code Wire} becomes
	 * connected.
	 * 
	 * <p>
	 * A {@code Wire} object is disconnected when either the Consumer or
	 * Producer service is unregistered or the {@code Wire} object is deleted.
	 * <p>
	 * A {@code WireAdminEvent} of type {@link WireAdminEvent#WIRE_DISCONNECTED}
	 * must be broadcast by the Wire Admin service when the {@code Wire} becomes
	 * disconnected.
	 * 
	 * @return {@code true} if both the Producer and Consumer for this
	 *         {@code Wire} object are connected to the {@code Wire} object;
	 *         {@code false} otherwise.
	 */
	public boolean isConnected();

	/**
	 * Return the list of data types understood by the Consumer service
	 * connected to this {@code Wire} object. Note that subclasses of the
	 * classes in this list are acceptable data types as well.
	 * 
	 * <p>
	 * The list is the value of the
	 * {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} service property of the
	 * Consumer service object connected to this object. If no such property was
	 * registered or the type of the property value is not {@code Class[]}, this
	 * method must return {@code null}.
	 * 
	 * @return An array containing the list of classes understood by the
	 *         Consumer service or {@code null} if the {@code Wire} is not
	 *         connected, or the consumer did not register a
	 *         {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} property or the
	 *         value of the property is not of type {@code Class[]}.
	 */
	public Class<?>[] getFlavors();

	/**
	 * Update the value.
	 * 
	 * <p>
	 * This methods is called by the Producer service to notify the Consumer
	 * service connected to this {@code Wire} object of an updated value.
	 * <p>
	 * If the properties of this {@code Wire} object contain a
	 * {@link WireConstants#WIREADMIN_FILTER} property, then filtering is
	 * performed. If the Producer service connected to this {@code Wire} object
	 * was registered with the service property
	 * {@link WireConstants#WIREADMIN_PRODUCER_FILTERS}, the Producer service
	 * will perform the filtering according to the rules specified for the
	 * filter. Otherwise, this {@code Wire} object will perform the filtering of
	 * the value.
	 * <p>
	 * If no filtering is done, or the filter indicates the updated value should
	 * be delivered to the Consumer service, then this {@code Wire} object must
	 * call the {@link Consumer#updated(Wire, Object)} method with the updated
	 * value. If this {@code Wire} object is not connected, then the Consumer
	 * service must not be called and the value is ignored.
	 * <p>
	 * If the value is an {@code Envelope} object, and the scope name is not
	 * permitted, then the {@code Wire} object must ignore this call and not
	 * transfer the object to the Consumer service.
	 * 
	 * <p>
	 * A {@code WireAdminEvent} of type {@link WireAdminEvent#WIRE_TRACE} must
	 * be broadcast by the Wire Admin service after the Consumer service has
	 * been successfully called.
	 * 
	 * @param value The updated value. The value should be an instance of one of
	 *        the types returned by {@link #getFlavors()}.
	 * @see WireConstants#WIREADMIN_FILTER
	 */
	public void update(Object value);

	/**
	 * Poll for an updated value.
	 * 
	 * <p>
	 * This methods is normally called by the Consumer service to request an
	 * updated value from the Producer service connected to this {@code Wire}
	 * object. This {@code Wire} object will call the
	 * {@link Producer#polled(Wire)} method to obtain an updated value. If this
	 * {@code Wire} object is not connected, then the Producer service must not
	 * be called.
	 * <p>
	 * 
	 * If this {@code Wire} object has a scope, then this method must return an
	 * array of {@code Envelope} objects. The objects returned must match the
	 * scope of this object. The {@code Wire} object must remove all
	 * {@code Envelope} objects with a scope name that is not in the
	 * {@code Wire} object's scope. Thus, the list of objects returned must only
	 * contain {@code Envelope} objects with a permitted scope name. If the
	 * array becomes empty, {@code null} must be returned.
	 * 
	 * <p>
	 * A {@code WireAdminEvent} of type {@link WireAdminEvent#WIRE_TRACE} must
	 * be broadcast by the Wire Admin service after the Producer service has
	 * been successfully called.
	 * 
	 * @return A value whose type should be one of the types returned by
	 *         {@link #getFlavors()},{@code Envelope[]}, or {@code null} if the
	 *         {@code Wire} object is not connected, the Producer service threw
	 *         an exception, or the Producer service returned a value which is
	 *         not an instance of one of the types returned by
	 *         {@link #getFlavors()}.
	 */
	public Object poll();

	/**
	 * Return the last value sent through this {@code Wire} object.
	 * 
	 * <p>
	 * The returned value is the most recent, valid value passed to the
	 * {@link #update(Object)} method or returned by the {@link #poll()} method
	 * of this object. If filtering is performed by this {@code Wire} object,
	 * this methods returns the last value provided by the Producer service.
	 * This value may be an {@code Envelope[]} when the Producer service uses
	 * scoping. If the return value is an Envelope object (or array), it must be
	 * verified that the Consumer service has the proper WirePermission to see
	 * it.
	 * 
	 * @return The last value passed though this {@code Wire} object or
	 *         {@code null} if no valid values have been passed or the Consumer
	 *         service has no permission.
	 */
	public Object getLastValue();

	/**
	 * Return the wire properties for this {@code Wire} object.
	 * 
	 * @return The properties for this {@code Wire} object. The returned
	 *         {@code Dictionary} must be read only.
	 */
	public Dictionary<String, Object> getProperties();

	/**
	 * Return the calculated scope of this {@code Wire} object.
	 * 
	 * The purpose of the {@code Wire} object's scope is to allow a Producer
	 * and/or Consumer service to produce/consume different types over a single
	 * {@code Wire} object (this was deemed necessary for efficiency reasons).
	 * Both the Consumer service and the Producer service must set an array of
	 * scope names (their scope) with the service registration property
	 * {@code WIREADMIN_PRODUCER_SCOPE}, or {@code WIREADMIN_CONSUMER_SCOPE}
	 * when they can produce multiple types. If a Producer service can produce
	 * different types, it should set this property to the array of scope names
	 * it can produce, the Consumer service must set the array of scope names it
	 * can consume. The scope of a {@code Wire} object is defined as the
	 * intersection of permitted scope names of the Producer service and
	 * Consumer service.
	 * <p>
	 * If neither the Consumer, or the Producer service registers scope names
	 * with its service registration, then the {@code Wire} object's scope must
	 * be {@code null}.
	 * <p>
	 * The {@code Wire} object's scope must not change when a Producer or
	 * Consumer services modifies its scope.
	 * <p>
	 * A scope name is permitted for a Producer service when the registering
	 * bundle has {@code WirePermission[name,PRODUCE]}, and for a Consumer
	 * service when the registering bundle has
	 * {@code WirePermission[name,CONSUME]}.
	 * <p>
	 * If either Consumer service or Producer service has not set a
	 * {@code WIREADMIN_*_SCOPE} property, then the returned value must be
	 * {@code null}.
	 * <p>
	 * If the scope is set, the {@code Wire} object must enforce the scope names
	 * when {@code Envelope} objects are used as a parameter to update or
	 * returned from the {@code poll} method. The {@code Wire} object must then
	 * remove all {@code Envelope} objects with a scope name that is not
	 * permitted.
	 * 
	 * @return A list of permitted scope names or null if the Produce or
	 *         Consumer service has set no scope names.
	 */
	public String[] getScope();

	/**
	 * Return true if the given name is in this {@code Wire} object's scope.
	 * 
	 * @param name The scope name
	 * @return true if the name is listed in the permitted scope names
	 */
	public boolean hasScope(String name);
}