org.eclipse.rse.core.subsystems
Interface IRemoteObjectResolver

All Known Subinterfaces:

IFileServiceSubSystem, IProcessServiceSubSystem, IRemoteCmdSubSystem, IRemoteFileSubSystem, IRemoteProcessSubSystem, IServiceSubSystem, IShellServiceSubSystem, ISubSystem

All Known Implementing Classes:

FileServiceSubSystem, ProcessServiceSubSystem, RemoteCmdSubSystem, RemoteFileSubSystem, RemoteProcessSubSystemImpl, ServiceSubSystem, ShellServiceSubSystem, SubSystem

public interface IRemoteObjectResolver

Interface for resolving an object in a subsystem from a unique ID. This is the functional opposite of IRemoteObjectIdentifier.

See Also:

IRemoteObjectIdentifier

Method Summary

Object

getObjectWithAbsoluteName(String key) Return the remote object that corresponds to the specified unique ID.

Method Detail

getObjectWithAbsoluteName

Object getObjectWithAbsoluteName(String key)
                                 throws Exception

Return the remote object that corresponds to the specified unique ID.

This must be implemented by subsystems in order to find remote objects for drag and drop, clipboard, and other object retrieval mechanisms in support of remote objects. It is the functional opposite of IRemoteObjectIdentifier.getAbsoluteName(Object).

Because each subsystem maintains it's own objects, it is the responsibility of the subsystem to determine how an ID (or key) for a given object maps to the real object. Subsystems also need to ensure that objects of different type (such as filters, actual resources or error messages) all have different IDs. See IRemoteObjectIdentifier.getAbsoluteName(Object) for an example.

In case a cached copy of remote object is available locally, this method will not contact the remote side in order to check whether the cached copy is up-to-date. Clients are responsible themselves for refreshing the remote object when they think it is necessary.

In case a cached local copy is not available, the remote system may be contacted to retrieve the remote object. In this case, this call may be a long-running operation and may throw an exception. Note, however, that since keys used as IDs are generated by a remote object adapter that implements IRemoteObjectIdentifier, a cached copy of the remote object will typically be in memory from generating the key. A notable exception to this case is when the system view is restored to its previous state during startup.

Uniqueness and Multiple Contexts
The RSE SystemView allows the same remote object to be displayed in multiple different contexts, i.e. under multiple different filters. In this case, each occurrence of the same object must return the same absolute name. For the reverse mapping, however, this method may return only one context object even though multiple different ones are shown in the SystemView.

Parameters:

key - the unique id of the remote object. Must not be null.

Returns:

the remote object instance, or null if no object is found with the given id.

Throws:

Exception - in case an error occurs contacting the remote system while retrieving the requested remote object. Extenders are encouraged to throw SystemMessageException in order to support good user feedback in case of errors. Since exceptions should only occur while retrieving new remote objects during startup, clients are typically allowed to ignore these exceptions and treat them as if the remote object were simply not there.

See Also:

IRemoteObjectIdentifier.getAbsoluteName(Object)