org.jinterop.dcom.common
Class JISystem

java.lang.Object
  extended by org.jinterop.dcom.common.JISystem

public final class JISystem
extends java.lang.Object

Class implemented for defining system wide changes.

A note on logging: The framework exposes JRE based logger "org.jinterop". Applications need to attach their own handler to this logger. If you would like to set the in-built handler, which writes to a file j-Interop.log in the java.io.tmpdir directory, please use the setInBuiltLogHandler(boolean). Please note that the level for the logger and all other configuration parameters should be set directly on the logger instance, using LogManager.getLogger("org.jinterop")

Note: Methods starting with internal_ keyword are internal to the framework and must not be called by the developer.

Since:
1.0

Method Summary
static java.lang.String getClsidFromProgId(java.lang.String progId)
          Queries the property file maintaining the PROGID Vs CLSID mappings and returns the CLSID if found or null otherwise.
static JIComVersion getCOMVersion()
          Returns COM version currently being used by the library.
static java.util.ResourceBundle getErrorMessages()
          Returns the ResourceBundle associated with current locale.
static java.lang.String getIPForHostName(java.lang.String hostname)
          Returns I.P address for the given hostname.
static java.util.Locale getLocale()
          Returns current locale associated with the library.
static java.lang.String getLocalizedMessage(int code)
          Returns the localized error messages for the error code.
static java.util.logging.Logger getLogger()
          Returns the framework logger identified by the name "org.jinterop".
static void internal_dumpMap()
           
static java.lang.Object internal_getSocket()
          synchronisation will be performed by the oxid master
static void internal_initLogger()
           
static void internal_setClsidtoProgId(java.lang.String progId, java.lang.String clsid)
          Stores it in a temporary hash map here, and this is later persisted when the library is shutdown
static void internal_setSocket(java.lang.Object socket)
          synchronisation will be performed by the oxid master
static void internal_writeProgIdsToFile()
          Should be called from system shut down only
static boolean isAutoRegistrationSet()
          Returns true is auto registration is enabled.
static boolean isJavaCoClassAutoCollectionSet()
          Status of autoCollection flag.
static void mapHostNametoIP(java.lang.String hostname, java.lang.String IP)
          Adds a mapping between the hostname and its IP.
static void setAutoRegisteration(boolean autoRegisteration)
          Indicates to the framework, if Windows Registry settings for DLL\OCX component identified by this object should be modified to add a Surrogate automatically.
static void setCOMVersion(JIComVersion comVersion)
          Sets the COM version which the library would use for communicating with COM servers.
static void setInBuiltLogHandler(boolean useParentHandlers)
          Used to set the in built log handler.
static void setJavaCoClassAutoCollection(boolean autoCollection)
          Sometimes the DCOM runtime of Windows will not send a ping on time to the Framework.
static void setLocale(java.util.Locale locale)
          Sets the locale, this locale will be used to retrieve the resource bundle for Error Messages.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getLogger

public static java.util.logging.Logger getLogger()
Returns the framework logger identified by the name "org.jinterop".

Returns:

setCOMVersion

public static void setCOMVersion(JIComVersion comVersion)
Sets the COM version which the library would use for communicating with COM servers. Default is 5.2.

Parameters:
comVersion - new COM version

getCOMVersion

public static JIComVersion getCOMVersion()
Returns COM version currently being used by the library.

Returns:

setLocale

public static void setLocale(java.util.Locale locale)
Sets the locale, this locale will be used to retrieve the resource bundle for Error Messages.

Parameters:
locale - default is Locale.getDefault().

getLocale

public static java.util.Locale getLocale()
Returns current locale associated with the library.

Returns:

getErrorMessages

public static java.util.ResourceBundle getErrorMessages()
Returns the ResourceBundle associated with current locale.

Returns:

getLocalizedMessage

public static java.lang.String getLocalizedMessage(int code)
Returns the localized error messages for the error code.

Parameters:
code - error code
Returns:

getClsidFromProgId

public static java.lang.String getClsidFromProgId(java.lang.String progId)
Queries the property file maintaining the PROGID Vs CLSID mappings and returns the CLSID if found or null otherwise.

Parameters:
progId - user friendly string such as "Excel.Application".
Returns:

internal_writeProgIdsToFile

public static void internal_writeProgIdsToFile()
Should be called from system shut down only


internal_setClsidtoProgId

public static void internal_setClsidtoProgId(java.lang.String progId,
                                             java.lang.String clsid)
Stores it in a temporary hash map here, and this is later persisted when the library is shutdown


internal_getSocket

public static java.lang.Object internal_getSocket()
synchronisation will be performed by the oxid master

Returns:

internal_setSocket

public static void internal_setSocket(java.lang.Object socket)
synchronisation will be performed by the oxid master


internal_initLogger

public static void internal_initLogger()

setAutoRegisteration

public static void setAutoRegisteration(boolean autoRegisteration)
Indicates to the framework, if Windows Registry settings for DLL\OCX component identified by this object should be modified to add a Surrogate automatically. A Surrogate is a process which provides resources such as memory and cpu for a DLL\OCX to execute.

This API overrides the instance specific flags set on JIClsid or JIProgID.

Parameters:
autoRegisteration - true if auto registration should be done by the framework.

isAutoRegistrationSet

public static boolean isAutoRegistrationSet()
Returns true is auto registration is enabled.

Returns:

setJavaCoClassAutoCollection

public static void setJavaCoClassAutoCollection(boolean autoCollection)

Sometimes the DCOM runtime of Windows will not send a ping on time to the Framework. It is not very abnormal, since Windows can sometimes resort to mechanisms other than DCOM to keep a reference count for the instances they imported. In case of j-Interop framework, if a ping is not received in 8 minutes , the Java Local Class is collected for GC. And if the COM server requires a reference to it or acts on a previously obtained reference , it is sent back an Exception. Please use this flag to set the Auto Collection status to ON or OFF. By Default, it is ON.

Parameters:
autoCollection - false if auto collection should be turned off.

isJavaCoClassAutoCollectionSet

public static boolean isJavaCoClassAutoCollectionSet()
Status of autoCollection flag.

Returns:
true if autoCollection is enabled, false otherwise.

setInBuiltLogHandler

public static void setInBuiltLogHandler(boolean useParentHandlers)
                                 throws java.lang.SecurityException,
                                        java.io.IOException
Used to set the in built log handler.

Parameters:
useParentHandlers - true if parent handlers should be used.
Throws:
java.io.IOException
java.lang.SecurityException

mapHostNametoIP

public static void mapHostNametoIP(java.lang.String hostname,
                                   java.lang.String IP)
                            throws java.net.UnknownHostException
Adds a mapping between the hostname and its IP. This method should be used when there is a possibility of multiple adapters (for example from a Virtual Machine) on the COM server. j-Interop Framework only uses the host name and ignores the I.P addresses supplied in the interface reference of a COM object. If this hostname is not reachable from the machine where library is currently running (such as a Linux machine with no name mappings) then the call to this COM server would fail with an UnknownHostException. To avoid that either add the binding in the host machine or add the binding here.

This method stores the name vs I.P binding in a Map. Providing the same hostname will overwrite the binding specified before.

Parameters:
hostname - name of target machine.
IP - address of target machine in I.P format.
Throws:
java.net.UnknownHostException - if the IP is invalid or cannot be reached.
java.lang.IllegalArgumentException - if any parameter is null or of 0 length.

getIPForHostName

public static java.lang.String getIPForHostName(java.lang.String hostname)
Returns I.P address for the given hostname.

Parameters:
hostname -
Returns:
null if a mapping could not be found.

internal_dumpMap

public static void internal_dumpMap()