ridljar/com/sun/star/uno/IEnvironment.java

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