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