org.jinterop.dcom.core
Class JIComServer

java.lang.Object
  extended by Stub
      extended by org.jinterop.dcom.core.JIComServer

public class JIComServer
extends Stub

Represents a COM Server. This is the startup class for using j-Interop to interoperate with a COM component.
Sample Usage:-
JISession session = JISession.createSession("DOMAIN","USERNAME","PASSWORD");
JIComServer excelServer = new JIComServer(JIProgId.valueOf(session,"Excel.Application"),address,session);
IJIComObject excelServerObject = excelServer.createInstance();
//Obtaining the IJIDispatch (if supported)
IJIDispatch dispatch = (IJIDispatch)JIComFactory.createCOMInstance(JIComFactory.IID_IDispatch,excelServerObject);

Each instance of JIComServer belongs to 1 session only. The session is responsible for all the reference counting and subsequent garbage collection of this instance.

Since:
1.0

Constructor Summary
JIComServer(JIClsid clsid, JISession session)
          Instantiates this object with JIClsid which is, according to MSDN:-
A universally unique identifier (UUID) that identifies a type of Component Object Model (COM) object.
JIComServer(JIClsid clsid, java.lang.String address, JISession session)
          Instantiates this object with JIClsid which is, according to MSDN:-
A universally unique identifier (UUID) that identifies a type of Component Object Model (COM) object.
JIComServer(JIProgId progId, JISession session)
          Instantiates this object with JIProgId which is, according to MSDN:-
A ProgID, or programmatic identifier, is a registry entry that can be associated with a JIClsid.
JIComServer(JIProgId progId, java.lang.String address, JISession session)
           Instantiates this object with JIProgId which is, according to MSDN:-
JIComServer(JISession session, JIInterfacePointer interfacePointer, java.lang.String ipAddress)
           Instantiates a JIComServer represented by the interfacePointer param.
 
Method Summary
 IJIComObject createInstance()
          Returns a IJIComObject representing the COM Server.
 IJIComObject getInstance()
          Returns a IJIComObject representing the COM Server.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JIComServer

public JIComServer(JISession session,
                   JIInterfacePointer interfacePointer,
                   java.lang.String ipAddress)
            throws JIException

Instantiates a JIComServer represented by the interfacePointer param. There are cases where a COM server may hand down a reference to a different COM server(which may or may not be on the same machine) and we would like to hook in between. The IJIComObject interface is usable only in the context of the current JIComServer, but when the interfacePointer is of a completely different COM server, the JIComFactory APIs will not work. The reason is the interface pointer passed to those APIs expects to belong only to a single and same COM server (say 'A'). If by any chance, that COM server passes a reference to you of another COM server (say 'B') on a different machine, the IJIComObject so returned from JIComFactory APIs will result in "Method not found" Exceptions (or others) since the pointer returned via that will always place calls to 'A' instead of 'B'. Under such scenarios you must use this API. This is not a usual case and for reasons related to nature of DCOM, will be very well documented in the Developers guide of your COM server.

The DCOM specs refer to this as the "middleman" case. (Section 3.3.1)

Parameters:
session - Please use a new session and not an already bounded one. The JISession.createSession(JISession) can be used to create a new session.
interfacePointer - reference to a different COM server pointer.
ipAddress - Can be null. Sometimes there are many adapters (virtual as well) on the Target machine to which this interface pointer belongs, which may get sent as part of the interface pointer and consequently this call will fail since it is a possibility that IP is not reachable via this machine. The developer can send in the valid IP and if found in the interface pointer list will be used to talk to the target machine, overriding the other IP addresses present in the interface pointer. If this IP is not found then the "machine name" binding will be used. If this param is null then the first binding obtained from the interface pointer is used.
Throws:
JIException

JIComServer

public JIComServer(JIProgId progId,
                   JISession session)
            throws JIException,
                   java.net.UnknownHostException

Instantiates this object with JIProgId which is, according to MSDN:-
A ProgID, or programmatic identifier, is a registry entry that can be associated with a JIClsid. The format of a ProgID is .., separated by periods and with no spaces, as in Word.Document.6. Like the JIClsid, the ProgID identifies a class, but with less precision.
ProgId is searched for it's JIClsid in the target servers registry. For the very first run, calling with ProgId will result in 3 extra calls to the server (for JIClsid resolution). Subsequently the j-Interop Library caches the JIClsid for this progId and uses that. It is also stored in a properties file (progIdVsClsidDB.properties) and reffered from there. We can save on the 3 calls in the subsequent runs also.
This call works on the LOCALHOST.

Parameters:
progId - Id like "Excel.Application" , "TestCOMServer.Test123" e.t.c
session - User's session.
Throws:
java.lang.IllegalArgumentException - raised when either progId or session is null.
JIException
java.net.UnknownHostException

JIComServer

public JIComServer(JIClsid clsid,
                   JISession session)
            throws java.lang.IllegalArgumentException,
                   JIException,
                   java.net.UnknownHostException

Instantiates this object with JIClsid which is, according to MSDN:-
A universally unique identifier (UUID) that identifies a type of Component Object Model (COM) object. Each type of COM object item has its JIClsid in the registry so that it can be loaded and used by other applications. For example, a spreadsheet may create worksheet items, chart items, and macrosheet items. Each of these item types has its own JIClsid that uniquely identifies it to the system.
This call works on the LOCALHOST.

Parameters:
clsid - 128 bit uuid like "00024500-0000-0000-C000-000000000046".
session - User's session.
Throws:
java.lang.IllegalArgumentException - raised when either clsid or session is null.
JIException
java.net.UnknownHostException

JIComServer

public JIComServer(JIProgId progId,
                   java.lang.String address,
                   JISession session)
            throws JIException,
                   java.net.UnknownHostException

Instantiates this object with JIProgId which is, according to MSDN:-

A ProgID, or programmatic identifier, is a registry entry that can be associated with a JIClsid. The format of a ProgID is .., separated by periods and with no spaces, as in Word.Document.6. Like the JIClsid, the ProgID identifies a class, but with less precision.
ProgId is searched for it's JIClsid in the target servers registry. For the very first run, calling with ProgId will result in 3 extra calls to the server (for JIClsid resolution). Subsequently the j-Interop Library caches the JIClsid for this progId and uses that. It is also stored in a properties file (progIdVsClsidDB.properties) and reffered from there. We can save on the 3 calls in the subsequent runs also.

Parameters:
progId - Id like "Excel.Application" , "TestCOMServer.Test123" e.t.c
address - address of the server where the COM object resides . This should be in the IEEE IP format (e.g. 192.168.170.6) or HostName.
session - User's session.
Throws:
java.lang.IllegalArgumentException - raised when either progId or address or session is null.
JIException
java.net.UnknownHostException

JIComServer

public JIComServer(JIClsid clsid,
                   java.lang.String address,
                   JISession session)
            throws JIException,
                   java.net.UnknownHostException

Instantiates this object with JIClsid which is, according to MSDN:-
A universally unique identifier (UUID) that identifies a type of Component Object Model (COM) object. Each type of COM object item has its JIClsid in the registry so that it can be loaded and used by other applications. For example, a spreadsheet may create worksheet items, chart items, and macrosheet items. Each of these item types has its own JIClsid that uniquely identifies it to the system. An IllegalArgumentException raised when either clsid or address or session is null.

Parameters:
clsid - 128 bit uuid like "00024500-0000-0000-C000-000000000046".
address - address of the server where the COM object resides . This should be in the IEEE IP format (e.g. 192.168.170.6) or HostName.
session - User's session.
Throws:
JIException
java.net.UnknownHostException
Method Detail

createInstance

public IJIComObject createInstance()
                            throws JIException
Returns a IJIComObject representing the COM Server. Not to be used with JIComServer(JISession,JIInterfacePointer,String) ctor, Use getInstance() instead.

Returns:
Throws:
JIException

getInstance

public IJIComObject getInstance()
                         throws JIException
Returns a IJIComObject representing the COM Server. To be used only with JIComServer(JISession,JIInterfacePointer,String) ctor, otherwise use createInstance() instead.

Returns:
Throws:
JIException