org.osgi.service.wireadmin.Envelope Maven / Gradle / Ivy
/*
* 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.
*
* 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();
}