IJIComObject (LSST CCS - OPC Driver 1.0.4 API)

All Superinterfaces:

Serializable

All Known Subinterfaces:

IJIDispatch, IJITypeInfo, IJITypeLib

All Known Implementing Classes:

JIComObjectImplWrapper
```
public interface IJIComObject
extends Serializable
```
Represents a Windows COM Object. Instances of this interface can be retrieved by the following ways only :-
- During initial handshake as expressed in the sample below.
- As references passed from Windows COM runtime such as when using queryInterface(String) or returned as [out] parameters to calls (directly as IJIComObject(s) or part of JIVariant (s)).
- From raw bytes using JIObjectFactory.buildObject(JISession, byte[])
- As references to local Java-COM interfaces (which are then used for event handling). See JIObjectFactory.buildObject(JISession, JILocalCoClass) for more details.
All references obtained by any mechanism stated above must be narrowed using JIObjectFactory.narrowObject(IJIComObject) before being casted to the expected type.

Sample usage :-
JISession session = JISession.createSession("DOMAIN","USERNAME","PASSWORD"); JIComServer comserver = new JIComServer(JIProgId.valueOf("Word.Application"),address,session); IJIComObject comObject = comserver.createInstance();
Also , IJIComObject handle = comObject.queryInterface("620012E2-69E3-4DC0-B553-AE252524D2F6");
Note: Methods starting with internal_ keyword are internal to the framework and must not be called by the developer.
Since:

1.0

Field Summary

Fields
Modifier and Type Field and Description

static String IID
IID representing the IUnknown.

Fields
Modifier and Type	Field and Description
`static String`	`IID` IID representing the `IUnknown`.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addRef()` Increases the reference count on the COM server by 5 (currently hard coded).
`Object[]`	`call(JICallBuilder obj)` Executes a method call on the actual COM object represented by this interface.
`Object[]`	`call(JICallBuilder obj, int timeout)` Refer `call(JICallBuilder)` for details on this method.
`JISession`	`getAssociatedSession()` Returns session associated with this object.
`int`	`getInstanceLevelSocketTimeout()` Returns the socket timeout set at the instance level.
`String`	`getInterfaceIdentifier()` Returns the COM IID of this object
`String`	`getIpid()` Unique 128 bit uuid representing the interface on the COM server.
`IJIUnreferenced`	`getUnreferencedHandler()` Returns the `IJIUnreferenced` handler associated with this object.
`Object[]`	`internal_getConnectionInfo(String identifier)` Framework Internal Returns the ConnectionPoint (IJIComObject) and it's Cookie.
`org.jinterop.dcom.core.JIInterfacePointer`	`internal_getInterfacePointer()` Framework Internal Returns self Interface pointer.
`Object[]`	`internal_removeConnectionInfo(String identifier)` Framework Internal Returns and Removes the connection info from the internal map.
`String`	`internal_setConnectionInfo(IJIComObject connectionPoint, Integer cookie)` Adds a connection point information and it's cookie to the connectionPointMap internally.
`void`	`internal_setDeffered(boolean deffered)` Framework Internal
`boolean`	`isDispatchSupported()` Returns `true` if `IDispatch` interface is supported by this object.
`boolean`	`isLocalReference()` Returns `true` if this COM object represents a local Java reference obtained by `JIObjectFactory.buildObject(JISession, JILocalCoClass)`.
`IJIComObject`	`queryInterface(String iid)` Retrieve interface references based on `iid`.
`void`	`registerUnreferencedHandler(IJIUnreferenced unreferenced)` Adds a `IJIUnreferenced` handler.
`void`	`release()` Decreases the reference count on the COM server by 5 (currently hard coded).
`void`	`setInstanceLevelSocketTimeout(int timeout)` Sets a timeout for all socket level operations done on this object.
`void`	`unregisterUnreferencedHandler()` Removes the `IJIUnreferenced` handler associated with this object.

- Field Detail
  - IID
```
static final String IID
```
    IID representing the IUnknown.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - queryInterface
```
IJIComObject queryInterface(String iid)
                     throws JIException
```
    Retrieve interface references based on iid. Make sure to narrow before casting to the expected type.
    For example when expecting an IJIEnumVariant :-
    IJIComObject object2 = variant.getObjectAsComObject(); IJIEnumVariant enumVariant = (IJIEnumVariant)JIObjectFactory.narrowObject(object2.queryInterface(IJIEnumVariant.IID));
    Throws IllegalStateException if isLocalReference() returns true.
    
    Parameters:
    
    iid - string representation of the IID.
    
    Returns:
    
    reference to the requested unknown.
    
    Throws:
    
    JIException
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
    
    See Also:
    
    JIObjectFactory.narrowObject(IJIComObject)
  - addRef
```
void addRef()
     throws JIException
```
    Increases the reference count on the COM server by 5 (currently hard coded). The developer should refrain from calling this API, as referencing is maintained internally by the system though he is not obligated to do so. If the release() is not called in conjunction with addRef then the COM Instance will not get garbage collected at the server.
    
    Throws:
    
    JIException
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
  - release
```
void release()
      throws JIException
```
    Decreases the reference count on the COM server by 5 (currently hard coded). The developer should refrain from calling this API, as referencing is maintained internally by the system though he is not obligated to do so. If the release is not called in conjunction with addRef() then the COM Instance will not get garbage collected at the server.
    
    Throws:
    
    JIException
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
  - getIpid
```
String getIpid()
```
    Unique 128 bit uuid representing the interface on the COM server. This value can and should be used to map an IJIUnreferenced handler implementation to this COM Object.
    Under NO circumstances should a reference to this COM object be stored any where for only purposes of "unreferenced" handling. This would hinder the way in which objects are garbage collected by the framework and this object would be forever "live".
    
    Returns:
    
    string representation of ipid.
  - call
```
Object[] call(JICallBuilder obj)
       throws JIException
```
    Executes a method call on the actual COM object represented by this interface. All the data like parameter information, operation number etc. are prepared and sent via the JICallBuilder.
    JICallBuilder obj = new JICallBuilder(); obj.reInit(); obj.setOpnum(0); //methods are sequentially indexed from 0 in the IDL obj.addInParamAsString(new JIString("j-Interop Rocks",JIFlags.FLAG_REPRESENTATION_STRING_LPCTSTR), JIFlags.FLAG_NULL); obj.addInParamAsPointer(new JIPointer(new JIString("Pretty simple ;)",JIFlags.FLAG_REPRESENTATION_STRING_LPCTSTR)), JIFlags.FLAG_NULL); Object[] result = comObject.call(obj);
    If return values are expected then set up the Out Params also in the JICallBuilder.
    The call timeout used here , by default is the instance level timeout. If no instance level timeout has been specified(or is 0) then the global timeout set in JISession will be used.
    
    Parameters:
    
    obj - call builder carrying all information necessary to make the call successfully.
    
    Returns:
    
    Object[] array representing the results in the order expected or set in JICallBuilder.
    
    Throws:
    
    JIException
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
    
    See Also:
    
    setInstanceLevelSocketTimeout(int), JISession.setGlobalSocketTimeout(int)
  - call
```
Object[] call(JICallBuilder obj,
              int timeout)
       throws JIException
```
    Refer call(JICallBuilder) for details on this method.
    
    Parameters:
    
    obj - call builder carrying all information necessary to make the call successfully.
    
    timeout - timeout for this call in milliseconds, overrides the instance level timeout. Passing 0 here will use the global socket timeout.
    
    Returns:
    
    Object[] array representing the results in the order expected or set in JICallBuilder.
    
    Throws:
    
    JIException
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
    
    See Also:
    
    JISession.setGlobalSocketTimeout(int)
  - setInstanceLevelSocketTimeout
```
void setInstanceLevelSocketTimeout(int timeout)
```
    Sets a timeout for all socket level operations done on this object. Calling this overrides the global socket timeout at the JISession level. To unset a previous timeout, pass 0 as a parameter.
    
    Parameters:
    
    timeout - timeout for this call in milliseconds
    
    Throws:
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
    
    See Also:
    
    JISession.setGlobalSocketTimeout(int)
  - getInstanceLevelSocketTimeout
```
int getInstanceLevelSocketTimeout()
```
    Returns the socket timeout set at the instance level. This timeout value is used during all socket level operations such as call(JICallBuilder) , queryInterface(String) etc.
    
    Returns:
    
    timeout set on this object in milliseconds.
    
    Throws:
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
  - internal_getInterfacePointer
```
org.jinterop.dcom.core.JIInterfacePointer internal_getInterfacePointer()
```
    Framework Internal Returns self Interface pointer.
  - getAssociatedSession
```
JISession getAssociatedSession()
```
    Returns session associated with this object.
    
    Returns:
    
    JISession
  - getInterfaceIdentifier
```
String getInterfaceIdentifier()
```
    Returns the COM IID of this object
    
    Returns:
    
    String representation of 128 bit uuid.
  - isDispatchSupported
```
boolean isDispatchSupported()
```
    Returns true if IDispatch interface is supported by this object.
    
    Returns:
    
    true if IDispatch is supported, false otherwise.
    
    Throws:
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
    
    See Also:
    
    IJIDispatch
  - internal_setConnectionInfo
```
String internal_setConnectionInfo(IJIComObject connectionPoint,
                                  Integer cookie)
```
    Adds a connection point information and it's cookie to the connectionPointMap internally. To be called only by the framework.
    
    Parameters:
    
    connectionPoint -
    
    cookie -
    
    Returns:
    
    unique identifier for the combination.
  - internal_getConnectionInfo
```
Object[] internal_getConnectionInfo(String identifier)
```
    Framework Internal Returns the ConnectionPoint (IJIComObject) and it's Cookie.
    
    Parameters:
    
    identifier -
    
    Returns:
  - internal_removeConnectionInfo
```
Object[] internal_removeConnectionInfo(String identifier)
```
    Framework Internal Returns and Removes the connection info from the internal map.
    
    Parameters:
    
    identifier -
    
    Returns:
  - registerUnreferencedHandler
```
void registerUnreferencedHandler(IJIUnreferenced unreferenced)
```
    Adds a IJIUnreferenced handler. The handler will be invoked when this comObject goes out of reference and is removed from it's session by the library. Only a single handler can be added for each object. If a handler for this object already exists , it would be replaced by this call.
    
    Parameters:
    
    unreferenced - handler to get notification when reference count for this object hits 0 and is garbage collected by the library's runtime.
    
    Throws:
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
  - getUnreferencedHandler
```
IJIUnreferenced getUnreferencedHandler()
```
    Returns the IJIUnreferenced handler associated with this object.
    
    Returns:
    
    null if no handler is associated with this object.
    
    Throws:
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
  - unregisterUnreferencedHandler
```
void unregisterUnreferencedHandler()
```
    Removes the IJIUnreferenced handler associated with this object. No exception will be thrown if one does not exist for this object.
    
    Throws:
    
    IllegalStateException - if there is no session associated with this object or this object represents a local java reference.
  - internal_setDeffered
```
void internal_setDeffered(boolean deffered)
```
    Framework Internal
    
    Parameters:
    
    deffered -
  - isLocalReference
```
boolean isLocalReference()
```
    Returns true if this COM object represents a local Java reference obtained by JIObjectFactory.buildObject(JISession, JILocalCoClass).
    
    Returns:
    
    true if this is a local reference , false otherwise.

Interface IJIComObject

Field Summary

Method Summary

Field Detail

IID

Method Detail

queryInterface

addRef

release

getIpid

call

call

setInstanceLevelSocketTimeout

getInstanceLevelSocketTimeout

internal_getInterfacePointer

getAssociatedSession

getInterfaceIdentifier

isDispatchSupported

internal_setConnectionInfo

internal_getConnectionInfo

internal_removeConnectionInfo

registerUnreferencedHandler

getUnreferencedHandler

unregisterUnreferencedHandler

internal_setDeffered

isLocalReference