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

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