001    /*
002     * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.osgi.service.wireadmin;
017    
018    /**
019     * Identifies a contained value.
020     * 
021     * An <code>Envelope</code> object combines a status value, an identification
022     * object and a scope name. The <code>Envelope</code> object allows the use of
023     * standard Java types when a Producer service can produce more than one kind of
024     * object. The <code>Envelope</code> object allows the Consumer service to
025     * recognize the kind of object that is received. For example, a door lock could
026     * be represented by a <code>Boolean</code> object. If the <code>Producer</code>
027     * service would send such a <code>Boolean</code> object, then the Consumer
028     * service would not know what door the <code>Boolean</code> object represented.
029     * The <code>Envelope</code> object contains an identification object so the
030     * Consumer service can discriminate between different kinds of values. The
031     * identification object may be a simple <code>String</code> object, but it can
032     * also be a domain specific object that is mutually agreed by the Producer and
033     * the Consumer service. This object can then contain relevant information that
034     * makes the identification easier.
035     * <p>
036     * The scope name of the envelope is used for security. The Wire object must
037     * verify that any <code>Envelope</code> object send through the <code>update</code>
038     * method or coming from the <code>poll</code> method has a scope name that
039     * matches the permissions of both the Producer service and the Consumer service
040     * involved. The wireadmin package also contains a class <code>BasicEnvelope</code>
041     * that implements the methods of this interface.
042     * 
043     * @see WirePermission
044     * @see BasicEnvelope
045     * 
046     * @version $Revision: 5673 $
047     */
048    public interface Envelope {
049            /**
050             * Return the value associated with this <code>Envelope</code> object.
051             * 
052             * @return the value of the status item, or <code>null</code> when no item is
053             *         associated with this object.
054             */
055            public Object getValue();
056    
057            /**
058             * Return the identification of this <code>Envelope</code> object.
059             * 
060             * An identification may be of any Java type. The type must be mutually
061             * agreed between the Consumer and Producer services.
062             * 
063             * @return an object which identifies the status item in the address space
064             *         of the composite producer, must not be null.
065             */
066            public Object getIdentification();
067    
068            /**
069             * Return the scope name of this <code>Envelope</code> object.
070             * 
071             * Scope names are used to restrict the communication between the Producer
072             * and Consumer services. Only <code>Envelopes</code> objects with a scope
073             * name that is permitted for the Producer and the Consumer services must be
074             * passed through a <code>Wire</code> object.
075             * 
076             * @return the security scope for the status item, must not be null.
077             */
078            public String getScope();
079    }