/* * This file is part of the LibreOffice project. * * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. * * This file incorporates work covered by the following license notice: * * 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 . */ package com.sun.star.uno; /** * The interface implemented by UNO environments. * *
With this interface, objects can be registered at and revoked from an * environment.
* * @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. * *Such an object will typically be one of three things: *
The object actually registered may differ from the specified
* object
that is passed as an argument. This enables an
* environment to work in a multi-threaded scenario, where two threads can
* call registerInterface
for the same combination of
* oid
and type
at the same time; the race
* condition is solved by letting one of the calls register its argument
* object
, ignoring the argument object
of the
* other call, and letting both calls return the same
* object
.
The registered object is held only weakly by the environment. After a
* call to registerInterface
, a call to
* getRegisteredInterface
only succeeds as long as the
* registered object is still strongly reachable, and the registered object
* has not been explicitly revoked by calling
* revokeInterface
.
object
.
* 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
* object
should implement this type
.
* @return the registered object (may differ from the object
* passed in); will never be null
*/
Object registerInterface(Object object, String[] oid, Type type);
/**
* Explicitly revokes a UNO interface facet.
*
* Calls to registerInterface
and
* revokeInterface
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 revokeInterface
(and calls to
* revokeInterface
would no longer be necessary if the calling
* code does not want to control the temporal extent of the
* registration).
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.
* * @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 theobject
; will never be null
*/
String getRegisteredObjectIdentifier(Object object);
/**
* Lists the registered objects to System.out
.
*
* This is for debug purposes.
*/ void list(); }