public interface IJIComObject extends Serializable
Represents a Windows COM Object. Instances of this interface can be retrieved by the following ways only :-
queryInterface(String) or returned as [out] parameters
to calls (directly as IJIComObject(s) or part of JIVariant
(s)). JIObjectFactory.buildObject(JISession, byte[])JIObjectFactory.buildObject(JISession, JILocalCoClass)
for more details.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");
| Modifier and Type | Field and Description |
|---|---|
static String |
IID
IID representing the
IUnknown. |
| 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. |
static final String IID
IUnknown.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.
iid - string representation of the IID.JIExceptionIllegalStateException - if there is no session associated
with this object or this object represents a local java reference.JIObjectFactory.narrowObject(IJIComObject)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.
JIExceptionIllegalStateException - if there is no session associated
with this object or this object represents a local java reference.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.
JIExceptionIllegalStateException - if there is no session associated
with this object or this object represents a local java reference.String getIpid()
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".
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.
obj - call builder carrying all information necessary to make the call successfully.JICallBuilder.JIExceptionIllegalStateException - if there is no session associated
with this object or this object represents a local java reference.setInstanceLevelSocketTimeout(int),
JISession.setGlobalSocketTimeout(int)Object[] call(JICallBuilder obj, int timeout) throws JIException
Refer call(JICallBuilder) for details on this method.
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.JICallBuilder.JIExceptionIllegalStateException - if there is no session associated
with this object or this object represents a local java reference.JISession.setGlobalSocketTimeout(int)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.
timeout - timeout for this call in millisecondsIllegalStateException - if there is no session associated
with this object or this object represents a local java reference.JISession.setGlobalSocketTimeout(int)int getInstanceLevelSocketTimeout()
call(JICallBuilder)
, queryInterface(String) etc.IllegalStateException - if there is no session associated
with this object or this object represents a local java reference.org.jinterop.dcom.core.JIInterfacePointer internal_getInterfacePointer()
JISession getAssociatedSession()
String getInterfaceIdentifier()
boolean isDispatchSupported()
true if IDispatch interface is supported
by this object.true if IDispatch is supported, false
otherwise.IllegalStateException - if there is no session associated
with this object or this object represents a local java reference.IJIDispatchString internal_setConnectionInfo(IJIComObject connectionPoint, Integer cookie)
connectionPoint - cookie - Object[] internal_getConnectionInfo(String identifier)
identifier - Object[] internal_removeConnectionInfo(String identifier)
identifier - void registerUnreferencedHandler(IJIUnreferenced unreferenced)
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.unreferenced - handler to get notification when reference count for this object hits 0 and is
garbage collected by the library's runtime.IllegalStateException - if there is no session associated
with this object or this object represents a local java reference.IJIUnreferenced getUnreferencedHandler()
IJIUnreferenced handler associated with this object.IllegalStateException - if there is no session associated
with this object or this object represents a local java reference.void unregisterUnreferencedHandler()
IJIUnreferenced handler associated with this object. No exception will
be thrown if one does not exist for this object.IllegalStateException - if there is no session associated
with this object or this object represents a local java reference.void internal_setDeffered(boolean deffered)
deffered - boolean isLocalReference()
true if this COM object represents a local Java reference obtained by
JIObjectFactory.buildObject(JISession, JILocalCoClass).
true if this is a local reference , false otherwise.Copyright © 2017 LSST. All rights reserved.