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