1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 package com.sun.star.uno;
25 
26 /**
27  * The interface implemented by UNO environments.
28  *
29  * <p>With this interface, objects can be registered at and revoked from an
30  * environment.</p>
31  *
32  * @see com.sun.star.uno.IBridge
33  * @see com.sun.star.uno.IQueryInterface
34  * @see com.sun.star.uno.UnoRuntime
35  *
36  * @deprecated As of UDK 3.2, this interface is deprecated, without offering a
37  * replacement.
38  */
39 public interface IEnvironment {
40     /**
41      * Gets the context of this environment.
42      *
43      * @return the context of this environment
44      */
45     Object getContext();
46 
47     /**
48      * Gets the name of this environment.
49      *
50      * @return the name of this environment
51      */
52     String getName();
53 
54     /**
55      * Registers one UNO interface facet of an object.
56      *
57      * <p>Such an object will typically be one of three things:
58      * <ul>
59      * <li>A local Java object, to be mapped out of this environment via a given
60      *     bridge.</li>
61      * <li>A proxy object, mapped into this environment via some bridge
62      *     <var>B1</var>, and now to be mapped out of this environment via a
63      *     given bridge <var>B2</var>.</li>
64      * <li>A proxy object, created as a remote object is mapped into this
65      *     environment via a given bridge.</li>
66      * </ul></p>
67      *
68      * <p>The object actually registered may differ from the specified
69      * <code>object</code> that is passed as an argument.  This enables an
70      * environment to work in a multi-threaded scenario, where two threads can
71      * call <code>registerInterface</code> for the same combination of
72      * <code>oid</code> and <code>type</code> at the same time; the race
73      * condition is solved by letting one of the calls register its argument
74      * <code>object</code>, ignoring the argument <code>object</code> of the
75      * other call, and letting both calls return the same
76      * <code>object</code>.</p>
77      *
78      * <p>The registered object is held only weakly by the environment.  After a
79      * call to <code>registerInterface</code>, a call to
80      * <code>getRegisteredInterface</code> only succeeds as long as the
81      * registered object is still strongly reachable, and the registered object
82      * has not been explicitly revoked by calling
83      * <code>revokeInterface</code>.</p>
84      *
85      * @param object the object to register; must be non-null
86      * @param oid in-out parameter containing the OID of <code>object</code>.
87      *    This must be a non-null reference to an array of length at least one;
88      *    the zeroth element is used to pass the argument in and out.  If the
89      *    zeroth element is null on input, the OID will be computed and passed
90      *    out (that is, the zeroth element will never be null upon normal
91      *    return).
92      * @param type the UNO interface type to register.  This argument must be
93      *    non-null, and must denote a UNO interface type.  The given
94      *    <code>object</code> should implement this <code>type</code>.
95      * @return the registered object (may differ from the <code>object</code>
96      *     passed in); will never be null
97      */
98     Object registerInterface(Object object, String[] oid, Type type);
99 
100     /**
101      * Explicitly revokes a UNO interface facet.
102      *
103      * <p>Calls to <code>registerInterface</code> and
104      * <code>revokeInterface</code> must be paired.  A facet is only removed
105      * from the environment when it has been revoked as often as it has been
106      * registered.  This may change in the future, so that a facet would be
107      * removed upon the first call to <code>revokeInterface</code> (and calls to
108      * <code>revokeInterface</code> would no longer be necessary if the calling
109      * code does not want to control the temporal extent of the
110      * registration).</p>
111      *
112      * <p>It is not an error if the specified facet is not registered at this
113      * environment (either because no corresponding object has ever been
114      * registered, or it has been explicitly revoked, or it is no longer
115      * strongly reachable).  In such a case, this method simply does
116      * nothing.</p>
117      *
118      * @param oid the OID of the object to revoke; must be non-null
119      * @param type the UNO interface type of the object to revoke.  This
120      *     argument must be non-null, and must denote a UNO interface type.
121      */
122     void revokeInterface(String oid, Type type);
123 
124     /**
125      * Retrieves a registered object, specified by OID and UNO interface type.
126      *
127      * @param oid the OID of the object to retrieve; must be non-null
128      * @param type the UNO interface type of the object to retrieve.  This
129      *     argument must be non-null, and must denote a UNO interface type.
130      * @return the registered object, or null if none is found
131      */
132     Object getRegisteredInterface(String oid, Type type);
133 
134     /**
135      * Retrieves the OID for a registered object.
136      *
137      * @param object a registered object; must be non-null
138      * @return the OID of the <code>object</code>; will never be null
139      */
140     String getRegisteredObjectIdentifier(Object object);
141 
142     /**
143      * Lists the registered objects to <code>System.out</code>.
144      *
145      * <p>This is for debug purposes.</p>
146      */
147     void list();
148 }
149