/**************************************************************
 * 
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 * 
 *************************************************************/


package com.sun.star.uno;

/**
 * The interface implemented by UNO environments.
 *
 * <p>With this interface, objects can be registered at and revoked from an
 * environment.</p>
 *
 * @see com.sun.star.uno.IBridge
 * @see com.sun.star.uno.IQueryInterface
 * @see com.sun.star.uno.UnoRuntime
 *
 * @deprecated As of UDK 3.2, this interface is deprecated, without offering a
 * replacement.
 */
public interface IEnvironment {
    /**
     * Gets the context of this environment.
     *
     * @return the context of this environment
     */
    Object getContext();

    /**
     * Gets the name of this environment.
     *
     * @return the name of this environment
     */
    String getName();

    /**
     * Registers one UNO interface facet of an object.
     *
     * <p>Such an object will typically be one of three things:
     * <ul>
     * <li>A local Java object, to be mapped out of this environment via a given
     *     bridge.</li>
     * <li>A proxy object, mapped into this environment via some bridge
     *     <var>B1</var>, and now to be mapped out of this environment via a
     *     given bridge <var>B2</var>.</li>
     * <li>A proxy object, created as a remote object is mapped into this
     *     environment via a given bridge.</li>
     * </ul></p>
     *
     * <p>The object actually registered may differ from the specified
     * <code>object</code> that is passed as an argument.  This enables an
     * environment to work in a multi-threaded scenario, where two threads can
     * call <code>registerInterface</code> for the same combination of
     * <code>oid</code> and <code>type</code> at the same time; the race
     * condition is solved by letting one of the calls register its argument
     * <code>object</code>, ignoring the argument <code>object</code> of the
     * other call, and letting both calls return the same
     * <code>object</code>.</p>
     *
     * <p>The registered object is held only weakly by the environment.  After a
     * call to <code>registerInterface</code>, a call to
     * <code>getRegisteredInterface</code> only succeeds as long as the
     * registered object is still strongly reachable, and the registered object
     * has not been explicitly revoked by calling
     * <code>revokeInterface</code>.</p>
     *
     * @param object the object to register; must be non-null
     * @param oid in-out parameter containing the OID of <code>object</code>.
     *    This must be a non-null reference to an array of length at least one;
     *    the zeroth element is used to pass the argument in and out.  If the
     *    zeroth element is null on input, the OID will be computed and passed
     *    out (that is, the zeroth element will never be null upon normal
     *    return).
     * @param type the UNO interface type to register.  This argument must be
     *    non-null, and must denote a UNO interface type.  The given
     *    <code>object</code> should implement this <code>type</code>.
     * @return the registered object (may differ from the <code>object</code>
     *     passed in); will never be null
     */
    Object registerInterface(Object object, String[] oid, Type type);

    /**
     * Explicitly revokes a UNO interface facet.
     *
     * <p>Calls to <code>registerInterface</code> and
     * <code>revokeInterface</code> must be paired.  A facet is only removed
     * from the environment when it has been revoked as often as it has been
     * registered.  This may change in the future, so that a facet would be
     * removed upon the first call to <code>revokeInterface</code> (and calls to
     * <code>revokeInterface</code> would no longer be necessary if the calling
     * code does not want to control the temporal extent of the
     * registration).</p>
     *
     * <p>It is not an error if the specified facet is not registered at this
     * environment (either because no corresponding object has ever been
     * registered, or it has been explicitly revoked, or it is no longer
     * strongly reachable).  In such a case, this method simply does
     * nothing.</p>
     *
     * @param oid the OID of the object to revoke; must be non-null
     * @param type the UNO interface type of the object to revoke.  This
     *     argument must be non-null, and must denote a UNO interface type.
     */
    void revokeInterface(String oid, Type type);

    /**
     * Retrieves a registered object, specified by OID and UNO interface type.
     *
     * @param oid the OID of the object to retrieve; must be non-null
     * @param type the UNO interface type of the object to retrieve.  This
     *     argument must be non-null, and must denote a UNO interface type.
     * @return the registered object, or null if none is found
     */
    Object getRegisteredInterface(String oid, Type type);

    /**
     * Retrieves the OID for a registered object.
     *
     * @param object a registered object; must be non-null
     * @return the OID of the <code>object</code>; will never be null
     */
    String getRegisteredObjectIdentifier(Object object);

    /**
     * Lists the registered objects to <code>System.out</code>.
     *
     * <p>This is for debug purposes.</p>
     */
    void list();
}