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