com.sun.star.uno.IEnvironment Maven / Gradle / Ivy
Show all versions of ridl Show documentation
/**************************************************************
*
* 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.
*
* 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:
*
* - A local Java object, to be mapped out of this environment via a given
* bridge.
* - A proxy object, mapped into this environment via some bridge
* B1, and now to be mapped out of this environment via a
* given bridge B2.
* - A proxy object, created as a remote object is mapped into this
* environment via a given bridge.
*
*
* 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
.
*
* @param object the object to register; must be non-null
* @param oid in-out parameter containing the OID of 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 the object
; will never be null
*/
String getRegisteredObjectIdentifier(Object object);
/**
* Lists the registered objects to System.out
.
*
* This is for debug purposes.
*/
void list();
}