org.osgi.service.wireadmin.Envelope Maven / Gradle / Ivy
/*
* 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;
/**
* Identifies a contained value.
*
* An Envelope object combines a status value, an identification
* object and a scope name. The Envelope object allows the use of
* standard Java types when a Producer service can produce more than one kind of
* object. The 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 Boolean object. If the Producer
* service would send such a Boolean object, then the Consumer
* service would not know what door the Boolean object represented.
* The Envelope object contains an identification object so the
* Consumer service can discriminate between different kinds of values. The
* identification object may be a simple 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.
*
* The scope name of the envelope is used for security. The Wire object must
* verify that any Envelope object send through the update
* method or coming from the 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 BasicEnvelope
* that implements the methods of this interface.
*
* @see WirePermission
* @see BasicEnvelope
*
* @version $Revision: 5673 $
*/
public interface Envelope {
/**
* Return the value associated with this Envelope object.
*
* @return the value of the status item, or null when no item is
* associated with this object.
*/
public Object getValue();
/**
* Return the identification of this 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 Envelope object.
*
* Scope names are used to restrict the communication between the Producer
* and Consumer services. Only Envelopes objects with a scope
* name that is permitted for the Producer and the Consumer services must be
* passed through a Wire object.
*
* @return the security scope for the status item, must not be null.
*/
public String getScope();
}