org.osgi.service.wireadmin.Envelope Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2002, 2010). 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.
*
* 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
*
* @version $Id: 1b320a1161ba45d1fd6c203663210a47e3588ad2 $
*/
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();
}