KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > wireadmin > Envelope


1 /*
2  * $Header: /cvshome/build/org.osgi.service.wireadmin/src/org/osgi/service/wireadmin/Envelope.java,v 1.8 2006/06/16 16:31:43 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.service.wireadmin;
19
20 /**
21  * Identifies a contained value.
22  *
23  * An <code>Envelope</code> object combines a status value, an identification
24  * object and a scope name. The <code>Envelope</code> object allows the use of
25  * standard Java types when a Producer service can produce more than one kind of
26  * object. The <code>Envelope</code> object allows the Consumer service to
27  * recognize the kind of object that is received. For example, a door lock could
28  * be represented by a <code>Boolean</code> object. If the <code>Producer</code>
29  * service would send such a <code>Boolean</code> object, then the Consumer
30  * service would not know what door the <code>Boolean</code> object represented.
31  * The <code>Envelope</code> object contains an identification object so the
32  * Consumer service can discriminate between different kinds of values. The
33  * identification object may be a simple <code>String</code> object, but it can
34  * also be a domain specific object that is mutually agreed by the Producer and
35  * the Consumer service. This object can then contain relevant information that
36  * makes the identification easier.
37  * <p>
38  * The scope name of the envelope is used for security. The Wire object must
39  * verify that any <code>Envelope</code> object send through the <code>update</code>
40  * method or coming from the <code>poll</code> method has a scope name that
41  * matches the permissions of both the Producer service and the Consumer service
42  * involved. The wireadmin package also contains a class <code>BasicEnvelope</code>
43  * that implements the methods of this interface.
44  *
45  * @see WirePermission
46  * @see BasicEnvelope
47  *
48  * @version $Revision: 1.8 $
49  */
50 public interface Envelope {
51     /**
52      * Return the value associated with this <code>Envelope</code> object.
53      *
54      * @return the value of the status item, or <code>null</code> when no item is
55      * associated with this object.
56      */
57     public Object JavaDoc getValue();
58
59     /**
60      * Return the identification of this <code>Envelope</code> object.
61      *
62      * An identification may be of any Java type. The type must be mutually
63      * agreed between the Consumer and Producer services.
64      *
65      * @return an object which identifies the status item in the address space
66      * of the composite producer, must not be null.
67      */
68     public Object JavaDoc getIdentification();
69
70     /**
71      * Return the scope name of this <code>Envelope</code> object.
72      *
73      * Scope names are used to restrict the communication between the Producer
74      * and Consumer services. Only <code>Envelopes</code> objects with a scope
75      * name that is permitted for the Producer and the Consumer services must be
76      * passed through a <code>Wire</code> object.
77      *
78      * @return the security scope for the status item, must not be null.
79      */
80     public String JavaDoc getScope();
81 }
82
Popular Tags