Envelope.java

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

/**
 * Identifies a contained value.
 * 
 * An {@code Envelope} object combines a status value, an identification object
 * and a scope name. The {@code Envelope} object allows the use of standard Java
 * types when a Producer service can produce more than one kind of object. The
 * {@code Envelope} object allows the Consumer service to recognize the kind of
 * object that is received. For example, a door lock could be represented by a
 * {@code Boolean} object. If the {@code Producer} service would send such a
 * {@code Boolean} object, then the Consumer service would not know what door
 * the {@code Boolean} object represented. The {@code Envelope} object contains
 * an identification object so the Consumer service can discriminate between
 * different kinds of values. The identification object may be a simple
 * {@code String} object, but it can also be a domain specific object that is
 * mutually agreed by the Producer and the Consumer service. This object can
 * then contain relevant information that makes the identification easier.
 * <p>
 * The scope name of the envelope is used for security. The Wire object must
 * verify that any {@code Envelope} object send through the {@code update}
 * method or coming from the {@code poll} method has a scope name that matches
 * the permissions of both the Producer service and the Consumer service
 * involved. The wireadmin package also contains a class {@code BasicEnvelope}
 * that implements the methods of this interface.
 * 
 * @see WirePermission
 * @see BasicEnvelope
 * 
 * @author $Id: f00816c73a580110d13750ab217369fef8f11b7e $
 */
public interface Envelope {
	/**
	 * Return the value associated with this {@code Envelope} object.
	 * 
	 * @return the value of the status item, or {@code null} when no item is
	 *         associated with this object.
	 */
	public Object getValue();

	/**
	 * Return the identification of this {@code Envelope} object.
	 * 
	 * An identification may be of any Java type. The type must be mutually
	 * agreed between the Consumer and Producer services.
	 * 
	 * @return an object which identifies the status item in the address space
	 *         of the composite producer, must not be null.
	 */
	public Object getIdentification();

	/**
	 * Return the scope name of this {@code Envelope} object.
	 * 
	 * Scope names are used to restrict the communication between the Producer
	 * and Consumer services. Only {@code Envelopes} objects with a scope name
	 * that is permitted for the Producer and the Consumer services must be
	 * passed through a {@code Wire} object.
	 * 
	 * @return the security scope for the status item, must not be null.
	 */
	public String getScope();
}