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