The class that acts as a factory for xmog_jvm_loaders and thereby for our JVM abstraction. More...

#include <xmog_jvm_loader.h>

Inheritance diagram for xmog_jvm_loader:

Collaboration diagram for xmog_jvm_loader:

Public Types
typedef void(XMOG_CALLING_CONVENTION *	XMOG_CONFIG_HOOK) (void *pLoader, int when)
	A typedef for registration hooks. More...

Public Member Functions
virtual xmog_jvm *	load (bool bAcceptPreloadedJvm=true)
	Attempts to load a JVM or connect to a remote server that has a JVM. More...

virtual xmog_jvm *	get_jvm ()
	Returns the JVM wrapper instance if one already exists. More...

virtual void	set_jvm (xmog_jvm *jvm)
	Sets a JVM into the loader. More...

jint	getLoadResult (char **pMsg=NULL)
	Returns the error code from the load() operation. More...

jint	getLoadedJvms (xmog_jvm *pJvms, jsize size, jsize count)
	Returns all the JVMs that this process is associated with.

virtual void	setJvmPath (const char *jvmPath)
	Overrides the method from xmog_options. More...

virtual void	read (const char *file, XMOGVERSION vers=NULL, XMOGCONFIG conf=NULL, XMOGVERSION reserved0=NULL)
	Updates the instance's configuration data with information from the specified data source. More...

bool	getEnvironmentOverrides () const
	Returns `true` if environment variables can override configured settings.

jint	getProbableMaximumHeapSizeInMB () const
	Returns the probable maximum heapsize that the process can support or 0 if we have no idea.

Public Member Functions inherited from xmog_jvm_options
	xmog_jvm_options (const char *filename, XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0, bool bEnvOverrides=true)
	Creates an options object. More...

virtual void *	getInitArgs (jint jniVersion)
	Returns a pointer to an object that can be used to initialize a JVM. More...

virtual int	readJvmOptions (const char *file, XMOGVERSION vers=NULL, XMOGCONFIG conf=NULL, XMOGVERSION reserved0=NULL)
	Reads the JVM initialization options from a configuration file or the Windows registry. More...

virtual void	reset ()
	Reestablishes the default (uninitialized) values. More...

virtual void	setJniVersion (jint version)
	Sets the JNI version that is going to be used (in JRE 1.2.x or higher only). More...

virtual void	setJniVersion (const char *version)
	Sets the JNI version that is going to be used (in JRE 1.2.x or higher only). More...

virtual jint	getJniVersion ()
	Returns the configured JNI version. More...

virtual void	setIgnoreUnrecognized (bool ignore)
	Sets whether or not unrecognized initialization options should be ignored or not. More...

virtual void	setIgnoreUnrecognized (const char *ignore)
	Sets whether or not unrecognized initialization options should be ignored or not. More...

virtual bool	getIgnoreUnrecognized ()
	Returns whether or not unrecognized initialization options are ignored or not. More...

virtual void	setStackSizeInKB (jint ss)
	Sets the stack size for Java threads in kB. More...

virtual void	setStackSize (const char *ss)
	Sets the stack size for Java threads. More...

virtual jint	getStackSizeInKB ()
	Returns the stack size for Java threads in kB.

virtual void	setInitialHeapSizeInMB (jint ihs)
	Sets the initial heap size for Java threads in MB. More...

virtual void	setInitialHeapSize (const char *ihs)
	Sets the initial heap size. More...

virtual jint	getInitialHeapSizeInMB ()
	Returns the initial heapsize in MB.

virtual void	setMaximumHeapSizeInMB (jint mhs)
	Sets the maximum heap size in MB. More...

virtual void	setMaximumHeapSize (const char *mhs)
	Sets the maximum heap size. More...

virtual jint	getMaximumHeapSizeInMB ()
	Returns the configured maximum heap size in MB or `0` if none is configured.

virtual void	setDashDOption (const char name, const char value=0)
	Sets a `-D` option (a system property). More...

virtual char *	getDashDOption (const char *name)
	Returns the value of a `-D` option (a system property) or `NULL` if the option is undefined. More...

virtual void	removeDashDOption (const char *name)
	Removes a `-D` option (a system property) from the configuration. More...

virtual void	setDashXOption (const char name, const char value=0)
	Sets a `-X` option (a generic JVM option). More...

virtual char *	getDashXOption (const char *name)
	Returns the value of a `-X` option (a generic JVM option) or `NULL` if the option is undefined. More...

virtual void	removeDashXOption (const char *name)
	Removes a `-X` option (a generic JVM option) from the configuration. More...

virtual void	setOtherOption (const char namevalue, void ptr=0)
	Allows the specification of a JVM option that is neither a -D nor a -X option. More...

virtual void *	getOtherOption (const char *name)
	Allows the querying of a JVM option that is neither a -D nor a -X option. More...

virtual void	removeOtherOption (const char *name)
	Removes a JVM option that is neither a -D nor a -X option. More...

virtual void	setClassPath (const char *cp)
	Sets the system classpath. More...

virtual void	appendToClassPath (const char *cp)
	Appends a string to the system classpath. More...

virtual void	prependToClassPath (const char *cp)
	Prepends a string to the system classpath. More...

virtual char *	getClassPath ()
	Returns the configured system classpath.

virtual void	setLibraryPath (const char *lp)
	Sets the path on which the JVM searches for native libraries. More...

virtual void	appendToLibraryPath (const char *lp)
	Appends a string to the library search path. More...

virtual char *	getLibraryPath ()
	Returns the configured library search path.

virtual void	setExtensionsDirectories (const char *ed)
	Sets the path on which the JVM searches for jarfiles that are treated like system types. More...

virtual void	appendToExtensionsDirectories (const char *ed)
	Appends a directory to the extensions path. More...

virtual char *	getExtensionsDirectories ()
	Returns the configured extensions directories.

virtual void	setSecurityManager (const char *sm)
	Sets the class that is the security manager for the application. More...

virtual char *	getSecurityManager ()
	Returns the classname of the application's security manager. More...

virtual void	setSecurityPolicy (const char *policyFile)
	Sets the policy file containing security settings for the application. More...

virtual char *	getSecurityPolicy ()
	Returns the filename of the application's security policy. More...

virtual void	setVfprintf (XMOG_VFPRINTF vfp)
	Sets the `vfprintf` callback that the JVM uses for reporting JVM information. More...

virtual void	setVfprintf (const char *vfp)
	Sets the `vfprintf` callback that the JVM uses for reporting JVM information. More...

virtual XMOG_VFPRINTF	getVfprintf ()
	Returns the `vfprintf` callback that the JVM uses for reporting JVM information. More...

virtual void	setExit (XMOG_EXIT ex)
	Sets the callback that the JVM calls before exiting. More...

virtual void	setExit (const char *ex)
	Sets the callback that the JVM calls before exiting. More...

virtual XMOG_EXIT	getExit ()
	Returns the `exit` callback that the JVM calls before exiting. More...

virtual void	setAbort (XMOG_ABORT ab)
	Sets the callback that the JVM calls before aborting. More...

virtual void	setAbort (const char *ab)
	Sets the callback that the JVM calls before aborting. More...

virtual XMOG_ABORT	getAbort ()
	Returns the `abort` callback that the JVM calls before aborting. More...

virtual void	setDisableClassGC (bool dcgc)
	Sets the value of the `-Xnoclassgc` option. More...

virtual void	setDisableClassGC (const char *dcgc)
	Sets the value of the `-Xnoclassgc` option. More...

virtual bool	getDisableClassGC ()
	Returns the value of the `-Xnoclassgc` option. More...

virtual void	setEnableClassGC (bool ecgc)
	Sets the opposite of the value of the `-Xnoclassgc` option. More...

virtual void	setEnableClassGC (const char *ecgc)
	Sets the opposite of the value of the `-Xnoclassgc` option. More...

virtual bool	getEnableClassGC ()
	Returns the opposite of the value of the `-Xnoclassgc` option. More...

virtual void	setEnableVerboseGC (bool evgc)

virtual void	setEnableVerboseGC (const char *evgc)

virtual bool	getEnableVerboseGC ()

virtual void	setEnabledAssertions (const char *ea)

virtual void	appendToEnabledAssertions (const char *ea)

virtual char *	getEnabledAssertions ()

virtual void	setDisabledAssertions (const char *da)

virtual void	appendToDisabledAssertions (const char *da)

virtual char *	getDisabledAssertions ()

virtual void	setEnableSystemAssertions (bool esa)

virtual void	setEnableSystemAssertions (const char *esa)

virtual bool	getEnableSystemAssertions ()

virtual void	setDisableSystemAssertions (bool dsa)

virtual void	setDisableSystemAssertions (const char *dsa)

virtual bool	getDisableSystemAssertions ()

virtual void	setVerbosity (int v)

virtual void	setVerbosity (const char *v)

virtual void	setVerbosity (xmog_jvm_verbosity v)

virtual xmog_jvm_verbosity	getVerbosity ()
	Returns the configured JVM verbosity. More...

virtual void	setMixedMode (bool m)
	Sets the value of the `-Xmixed` option. More...

virtual void	setMixedMode (const char *m)
	Sets the value of the `-Xmixed` option. More...

virtual bool	getMixedMode ()
	Returns the value of the `-Xmixed` option. More...

virtual void	setInterpretedMode (bool i)
	Sets the value of the `-Xint` option. More...

virtual void	setInterpretedMode (const char *i)
	Sets the value of the `-Xint` option. More...

virtual bool	getInterpretedMode ()
	Returns the value of the `-Xint` option. More...

virtual void	setAppendBootClassPath (const char *cp)
	Sets the value of the `-Xbootclasspath/a:` option. More...

virtual void	appendToAppendBootClassPath (const char *cp)
	Appends a classpath root to the current value of the `-Xbootclasspath/a:` option. More...

virtual char *	getAppendBootClassPath ()
	Returns the value of the `-Xbootclasspath/a:` option. More...

virtual void	setPrependBootClassPath (const char *cp)
	Sets the value of the `-Xbootclasspath/p:` option. More...

virtual void	appendToPrependBootClassPath (const char *cp)
	Appends a classpath root to the current value of the `-Xbootclasspath/p:` option. More...

virtual char *	getPrependBootClassPath ()
	Returns the value of the `-Xbootclasspath/p:` option. More...

virtual void	setBootClassPath (const char *cp)
	Sets the value of the `-Xbootclasspath:` option. More...

virtual void	appendToBootClassPath (const char *cp)
	Appends a new classpath root to the value of the `-Xbootclasspath:` option. More...

virtual char *	getBootClassPath ()
	Returns the value of the `-Xbootclasspath:` option. More...

virtual void	setIncrementalGC (bool i)
	Enables or disables incremental garbage collection. More...

virtual void	setIncrementalGC (const char *i)
	Enables or disables incremental garbage collection. More...

virtual bool	getIncrementalGC ()
	Returns the value of the incremental garbage collection option. More...

virtual void	setLogGCFile (const char *file)
	Sets the log file used by the JVM. More...

virtual char *	getLogGCFile ()
	Returns the value of the garbage collection log file option. More...

virtual void	setBatchMode (bool b)
	Sets or clears the `-Xbatch` option. More...

virtual void	setBatchMode (const char *b)
	Sets or clears the `-Xbatch` option. More...

virtual bool	getBatchMode ()
	Returns `true` if the `-Xbatch` option is set, `false` otherwise.

virtual void	setProf (bool p)
	Sets the `-Xprof` option if `true`. More...

virtual void	setProf (const char *p)
	Sets the `-Xprof` option if `"true"`. More...

virtual bool	getProf ()
	Returns `true` if the `-Xprof` options is used.

virtual void	setRun (const char *runopts)
	Sets the `-Xrun` option. More...

virtual char *	getRun ()
	Returns the value of the `-Xrun` option.

virtual void	setDebug (bool d)
	Sets or clears the `-Xdebug` option. More...

virtual void	setDebug (const char *d)
	Sets or clears the `-Xdebug` option. More...

virtual bool	getDebug ()
	Returns `true` if the `-Xdebug` option is set, `false` otherwise.

virtual void	setNoagent (bool na)
	Sets or clears the `-Xnoagent` option. More...

virtual void	setNoagent (const char *na)
	Sets or clears the `-Xnoagent` option. More...

virtual bool	getNoagent ()
	Returns `true` if the `-Xnoagent` option is set, `false` otherwise.

virtual void	setReduceSignals (bool rs)
	Sets or clears the `-Xrs` option. More...

virtual void	setReduceSignals (const char *rs)
	Sets or clears the `-Xrs` option. More...

virtual bool	getReduceSignals ()
	Returns `true` if the `-Xrs` option is set, `false` otherwise.

virtual void	setCheckJni (bool cjni)
	Sets or clears the `-Xcheck:jni` option. More...

virtual void	setCheckJni (const char *cjni)
	Sets or clears the `-Xcheck:jni` option. More...

virtual bool	getCheckJni ()
	Returns `true` if the `-Xcheck:jni` option is set, `false` otherwise.

virtual void	setFuture (bool future)
	Sets or clears the `-Xfuture` option. More...

virtual void	setFuture (const char *future)
	Sets or clears the `-Xfuture` option. More...

virtual bool	getFuture ()
	Returns `true` if the `-Xfuture` option is set, `false` otherwise.

virtual void	addAgentLib (const char *pAgentLib)
	Add an `-agentlib:` option to the settings. More...

virtual void	addAgentPath (const char *pAgentPath)
	Add an `-agentpath:` option to the settings. More...

virtual void	addJavaAgent (const char *pJavaAgent)
	Add an `-javaagent:` option to the settings. More...

virtual void	mergeWithDefaults (JDK1_1InitArgs &iargs11)
	A deprecated JNI 1.1 option.

virtual void	setCheckSource (bool cs)
	A deprecated JNI 1.1 option.

virtual bool	getCheckSource ()
	A deprecated JNI 1.1 option.

virtual void	setNativeStackSizeInKB (jint nss)
	A deprecated JNI 1.1 option.

virtual jint	getNativeStackSizeInKB ()
	A deprecated JNI 1.1 option.

virtual void	setVerifyMode (xmog_bytecode_verification ver)
	A deprecated JNI 1.1 option.

virtual xmog_bytecode_verification	getVerifyMode ()
	A deprecated JNI 1.1 option.

virtual void	setDisableAsyncGC (bool dagc)
	A deprecated JNI 1.1 option.

virtual bool	getDisableAsyncGC ()
	A deprecated JNI 1.1 option.

virtual void	addModules (const char *pMdules)
	Add an –add-modules option to the setings. More...

virtual void	setModulePath (const char *mp)
	Sets the module path. More...

virtual void	appendToModulePath (const char *mp)
	Appends a string to the module path. More...

virtual void	prependToModulePath (const char *mp)
	Prepends a string to the module path. More...

virtual char *	getModulePath ()
	Returns the configured module path. More...

virtual void	addOpens (const char pMod, const char pPackage, const char *pReadingModule="ALL-UNNAMED")
	Opens a package to a module. More...

virtual void	addExports (const char pMod, const char pPackage, const char *pReadingModule="ALL-UNNAMED")
	Exports a package to a module. More...

virtual void	addReads (const char pModule, const char pModules)
	Enables a module to use public types from one or more other modules. More...

Static Public Member Functions
static void	setConfigFile (const char *filename, XMOGVERSION vers=NULL, XMOGCONFIG conf=NULL, XMOGVERSION reserved0=NULL)
	Specify the location of a config file and/or sub entries to be used when the runtime initializes. More...

static xmog_jvm_loader &	get_jvm_loader (bool bEnvOverrides=true, bool bDefaultJvm=true, xmog_trace_facility fac=TraceAll, xmog_trace_level trace_level=TraceErrors)
	The "default" factory method that creates the JVM loader instance that is to be used by the proxy classes to launch the JVM. More...

static xmog_jvm_loader &	get_jvm_loader (const char *filename, XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0=NULL, bool bEnvOverrides=true, bool bDefaultJvm=true, xmog_trace_facility fac=TraceAll, xmog_trace_level trace_level=TraceErrors)
	The backwards-compatibility factory method that creates the JVM loader instance based on information from an old-style JunC++ion configuration file. More...

static xmog_jvm_loader &	get_jvm_loader (const char *filename, bool bEnvOverrides=true, bool bDefaultJvm=true, xmog_trace_facility fac=TraceAll, xmog_trace_level trace_level=TraceErrors)
	The factory method that creates the JVM loader instance based on information from a new-style JuggerNET configuration file. More...

static xmog_jvm_loader &	get_jvm_loader (int argc, char *argv[], bool bEnvOverrides=true, bool bDefaultJvm=true, xmog_trace_facility fac=TraceAll, xmog_trace_level trace_level=TraceErrors)
	The factory method that creates the JVM loader instance based on commandline information. More...

static xmog_jvm_loader &	get_jvm_loader (XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0=NULL, bool bEnvOverrides=true, bool bDefaultJvm=true, xmog_trace_facility fac=TraceAll, xmog_trace_level trace_level=TraceErrors)
	The factory method that creates the JVM loader instance based on information retrieved from the Windows registry (on Windows only) or a configuration file in a default location (on non-Windows platforms). More...

static xmog_jvm_loader *	get_jvm_loader_no_create ()
	Returns a pointer to an already created xmog_jvm_loader or `null` if no loader has been created yet. More...

static bool	isNativeInitThread ()
	Returns true if the calling thread is the thread on which the JVM was initialized in native runtime mode.

static const char *	getDefaultJvmPath ()
	Returns the default path that could be used if no Jvm path has been set. More...

static bool	isInShutdownMode ()
	Returns true if we should not attempt to perform any more JVM-related activities. More...

static void	enterShutdownMode ()
	Enters shutdownmode. More...

static void	addVersionConfig (const char vers, const char config)
	Adds a version/config pair to the list of configurations. More...

static void	registerConfigurationHook (XMOG_CONFIG_HOOK configHook)
	Registers a configuration hook (a method that is called during the creation of a JVM loader). More...

static void	atexit_call ()
	Not intended to be called by developer.

Protected Member Functions
	xmog_jvm_loader (bool bEnvOverrides, bool bDefaultJvm, xmog_trace_facility fac, xmog_trace_level)
	The default constructor. More...

	xmog_jvm_loader (const char *filename, bool bEnvOverrides, bool bDefaultJvm, xmog_trace_facility fac, xmog_trace_level)
	The constructor allowing the specification of a configuration file. More...

	xmog_jvm_loader (const char *filename, XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0, bool bEnvOverrides, bool bDefaultJvm, xmog_trace_facility fac, xmog_trace_level)
	The constructor allowing the specification of a legacy configuration file or the registry. More...

	xmog_jvm_loader (int argc, char *argv[], bool bEnvOverrides, bool bDefaultJvm, xmog_trace_facility fac, xmog_trace_level)
	The constructor that parses a commandline. More...

	xmog_jvm_loader (XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0, bool bEnvOverrides, bool bDefaultJvm, xmog_trace_facility fac, xmog_trace_level)
	The constructor allowing the specification of a registry section. More...

xmog_jvm *	usePreloadedJvm ()
	Returns a preloaded JVM instance or `NULL` if no JVM is already loaded.

xmog_jvm *	loadInProcess (bool bAcceptPreloadedJvm)
	Returns a newly loaded JVM instance based on the configured settings. More...

xmog_jvm *	loadOutOfProcessClient (bool bAcceptPreloadedJvm)
	Returns a newly loaded JVM instance that represents a client connection to a shared JVM server. More...

xmog_jvm *	loadOutOfProcessServer (bool bAcceptPreloadedJvm)
	Returns a newly loaded JVM instance based on the configured settings. More...

xmog_jvm *	loadOutOfProcess (bool bAcceptPreloadedJvm, bool bServer=false)
	Returns a newly loaded JVM instance that represents a client or a server connection to a shared JVM server. More...

void	consolidateVersionConfigs ()
	Consolidates select options from multiple named configurations into the JVM loader instance. More...

void	addExtensionDirectories ()
	Adds the configured JRE's "ext" directory to the JVM configuration's extension directories. More...

Protected Member Functions inherited from xmog_jvm_options
	xmog_jvm_options (bool bEnvOverrides=true)

	xmog_jvm_options (const char *filename, bool bEnvOverrides=true)

	xmog_jvm_options (XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0, bool bEnvOverrides=true)

	xmog_jvm_options (int argc, char *argv[], bool bEnvOverrides=true)

void	env_override ()

Detailed Description

The class that acts as a factory for xmog_jvm_loaders and thereby for our JVM abstraction.

A developer can either rely on the default way the xmog_jvm_loader instance is created inside generated code or she can pre-create a loader instance using one of the factory methods. Each factory method supports a specific configuration mechanism that is used to gain access to the configuration information that will be used to initialize the JVM and the framework. The configuration information falls into different categories:

JVM initialization information, inherited from xmog_jvm_options
framework initialization information, inherited from xmog_options
remote initialization information, inherited from xmog_remote_client_options

The xmog_jvm_loader class aggregates all these types to provide one convenient way to configure all aspects of a proxy application's runtime.

You only need to create an xmog_jvm_loader instance once per session, in fact, you can only create one instance per session. After the first instance has been created, subsequent calls to one of the factory methods will return the original instance while disregarding any factory method arguments. This allows you to have initialization code in more than one place without running into any problems due to conflicting initialization information.

You can but you don't have to call load() explicitly. Calling load() explicitly allows you to control the time at which the JVM initialization takes place. This can be important if you could have user configured applications and need to have good configuration error handling. If you don't have a convenient place to call load() explicitly, you can rely on the on-demand loading of the JVM that is triggered whne you first use a generated proxy type. If you just create a xmog_jvm_loader instance without calling load(), you're essentially providing the instance that will be used by the on-demand loading mechanism.

You can combine configuration files (or registry information) with programmatic initialization. You can for example allow the user to specify certain values in external configuration files while controlling others in your application. This is illustrated in example 3.

The following examples illustrate the use of xmog_jvm_loader.

Example 1

xmog_jvm_loader &  loader = xmog_jvm_loader::get_jvm_loader( "c:\\temp\\app.config" );
 
loader.load();

This example creates a loader that uses the specified configuration file. In this case, the configuration file contains XML configuration information, so no additional version and configuration information is required. Strictly speaking, the load() call is only required if you want to control when the JVM is going to be loaded. If you don't load the JVM explicitly, the JVM will be on-demand loaded when the first proxy class code is being executed.

Example 2

xmog_jvm_loader &  loader = xmog_jvm_loader::get_jvm_loader( "c:\\temp\\config.dat", "2.0", "eval", false, true );
 
loader.load();

This example creates a loader that uses the specified configuration file, disallows environment variable overrides, and allows the use of a default JVM. In this case, the configuration file contains legacy style configuration information. The file could contain information for more than one different application which is why a version and configuration name are required.

Example 3

xmog_jvm_loader &  loader = xmog_jvm_loader::get_jvm_loader( "c:\\temp\\config.dat", "2.0", "eval" );
 
loader.setCheckJni( true );
loader.setVerbosity( "all" ); //other styles for setting the verbosity are available
 
loader.load();

This example creates a loader that uses the specified configuration file. In this case, the configuration file contains legacy style configuration information. The file could contain information for more than one different application which is why a version and configuration name are required. Then the configuration information from the config file is extended or overridden programmatically by calling the appropriate configuration API methods before the JVM is loaded by the load() method.

Example 4

xmog_jvm_loader &  loader = xmog_jvm_loader::get_jvm_loader();
 
loader.setVerbosity( "all" ); //other styles for setting the verbosity are available

This example creates a loader using the "default" factory method. The default factory method allows the specification of settings via environment variables, uses a default JVM, and sets the tracing level to TraceErrors for all tracing categories. This factory method is used by the framework when no other configuration information is available. In a typical application that uses generated proxy types, we're usually going to use a variation that looks for configuration information in a file or in the registry.

In this example, we're not calling load(), so we're just providing the framework with the loader instance that is going to be used by the on-demand initialization mechanism at a later time.

Constructor & Destructor Documentation

◆ xmog_jvm_loader() [1/5]

xmog_jvm_loader::xmog_jvm_loader	(	bool	bEnvOverrides,
		bool	bDefaultJvm,
		xmog_trace_facility	fac,
		xmog_trace_level
	)

protected

The default constructor.

Parameters

bEnvOverrides	`true` if environment variables can provide overrides for configuration settings.
bDefaultJvm	`true` if an already loaded JVM may be used. If `false`, an already loaded JVM will cause an error.
fac	the tracing facilities being set.

◆ xmog_jvm_loader() [2/5]

xmog_jvm_loader::xmog_jvm_loader	(	const char *	filename,
		bool	bEnvOverrides,
		bool	bDefaultJvm,
		xmog_trace_facility	fac,
		xmog_trace_level
	)

protected

The constructor allowing the specification of a configuration file.

Parameters

filename	the configuration file's name.
bEnvOverrides	`true` if environment variables can provide overrides for configuration settings.
bDefaultJvm	`true` if an already loaded JVM may be used. If `false`, an already loaded JVM will cause an error.
fac	the tracing facilities being set.

◆ xmog_jvm_loader() [3/5]

xmog_jvm_loader::xmog_jvm_loader	(	const char *	filename,
		XMOGVERSION	vers,
		XMOGCONFIG	conf,
		XMOGVERSION	reserved0,
		bool	bEnvOverrides,
		bool	bDefaultJvm,
		xmog_trace_facility	fac,
		xmog_trace_level
	)

protected

The constructor allowing the specification of a legacy configuration file or the registry.

This constructor is used by the legacy config file (or registry) mechanism of JunC++ion.

Parameters

filename	the configuration file's name.
vers	the version section in the file or registry.
conf	the configuration name section in the file or registry.
reserved0	should be `NULL`.
bEnvOverrides	`true` if environment variables can provide overrides for configuration settings.
bDefaultJvm	`true` if an already loaded JVM may be used. If `false`, an already loaded JVM will cause an error.
fac	the tracing facilities being set.

◆ xmog_jvm_loader() [4/5]

xmog_jvm_loader::xmog_jvm_loader	(	int	argc,
		char *	argv[],
		bool	bEnvOverrides,
		bool	bDefaultJvm,
		xmog_trace_facility	fac,
		xmog_trace_level
	)

protected

The constructor that parses a commandline.

Parameters

argc	the number of arguments.
argv	an array of arguments.
bEnvOverrides	`true` if environment variables can provide overrides for configuration settings.
bDefaultJvm	`true` if an already loaded JVM may be used. If `false`, an already loaded JVM will cause an error.
fac	the tracing facilities being set.

◆ xmog_jvm_loader() [5/5]

xmog_jvm_loader::xmog_jvm_loader	(	XMOGVERSION	vers,
		XMOGCONFIG	conf,
		XMOGVERSION	reserved0,
		bool	bEnvOverrides,
		bool	bDefaultJvm,
		xmog_trace_facility	fac,
		xmog_trace_level
	)

protected

The constructor allowing the specification of a registry section.

This constructor is used by the legacy config file (or registry) mechanism of JunC++ion.

Parameters

vers	the version section in the file or registry.
conf	the configuration name section in the file or registry.
reserved0	should be `NULL`.
bEnvOverrides	`true` if environment variables can provide overrides for configuration settings.
bDefaultJvm	`true` if an already loaded JVM may be used. If `false`, an already loaded JVM will cause an error.
fac	the tracing facilities being set.

Member Function Documentation

◆ addExtensionDirectories()

void xmog_jvm_loader::addExtensionDirectories ( )

protected

Adds the configured JRE's "ext" directory to the JVM configuration's extension directories.

This method is called just before the JVM is loaded in-process. You can for example deploy your jar files in your application's private "ext" directory, thereby making any classpath configuration unnecessary.

◆ addVersionConfig()

static void xmog_jvm_loader::addVersionConfig	(	const char *	vers,
		const char *	config
	)

static

Adds a version/config pair to the list of configurations.

This method is used by the framework to support multiple named configurations within one application. Calling this method with a version/config pair allows the framework to add the specified configuration items to the initial configuration. Most users never have to worry about this method, but it can come in handy when modules from different code generation sessions (using different configurations) are mixed in one application.

Usually, this method is called when an xmog_java_class instance that has been generated for a specific a named configuration is instantiated. Under typical circumstances, the calling process will only have proxy types that were generated for one named configuration and that means that there will only be one entry in the list of named configurations. Under rarer circumstances, a process will mix proxy types from more than one named configuration and that will cause more than one entry to be maintained in the list of named configurations.

◆ consolidateVersionConfigs()

void xmog_jvm_loader::consolidateVersionConfigs ( )

protected

Consolidates select options from multiple named configurations into the JVM loader instance.

If more than one named configuration is specified, some settings should be coalesced into one. For example the classpath that is used should be the "sum" of all classpaths, simply assuming that the configured classpath roots can coexist in one classloader.

The settings that are coalesced are:

the classpath
the append-bootclasspath
the prepend-bootclasspath
the maximum heap size (set to the largest found value)
the initial heap size (set to the largest found value)
the -D options (not yet implemented)

Todo:
Implement -D option merge

◆ enterShutdownMode()

static void xmog_jvm_loader::enterShutdownMode ( )

static

Enters shutdownmode.

Shutdown mode means that we're not going to attempt to perform any more framework calls (using JNI or whatever other mechanism is configured). This can be necessary for scenarios where the operating system unloads the JVM before other loaded DLLs attempt to clean up behind themselves.

◆ get_jvm()

virtual xmog_jvm* xmog_jvm_loader::get_jvm ( )

virtual

Returns the JVM wrapper instance if one already exists.

This method is a pure framework method. It does not perform any JNI checking for already loaded JVMs, it simply looks for an already created xmog_jvm instance and returns it if it exists.

In particular, this method will return NULL if no call to load() has occurred yet, even if a JVM exists in the process.

◆ get_jvm_loader() [1/5]

static xmog_jvm_loader& xmog_jvm_loader::get_jvm_loader	(	bool	bEnvOverrides = `true`,
		bool	bDefaultJvm = `true`,
		xmog_trace_facility	fac = `TraceAll`,
		xmog_trace_level	trace_level = `TraceErrors`
	)

static

The "default" factory method that creates the JVM loader instance that is to be used by the proxy classes to launch the JVM.

This constructor works well when the application is going to be programmatically configured or when you have previously called setConfigFile() to provide all required initialization arguments.

Parameters

bEnvOverrides	true if environment variables are to be supported. The default is true.
bDefaultJvm	true if a platform-specific default JVM should be used as a default if no JVM is specified. The default is that a default JVM is used if nothing is specified.
fac	the trace facilities that are active. The default is that all trace facilities are enabled.
trace_level	the trace level at which they are active. The default is that only errors are traced.

◆ get_jvm_loader() [2/5]

static xmog_jvm_loader& xmog_jvm_loader::get_jvm_loader	(	const char *	filename,
		bool	bEnvOverrides = `true`,
		bool	bDefaultJvm = `true`,
		xmog_trace_facility	fac = `TraceAll`,
		xmog_trace_level	trace_level = `TraceErrors`
	)

static

The factory method that creates the JVM loader instance based on information from a new-style JuggerNET configuration file.

In the new configuration file scheme, the configuration file itself contains all information that is required to select a particular section (and the format is XML, very much like a .NET config file). Use the other factory method that takes a filename and additional version and configname arguments to choose the old style of configuration.

Parameters

filename	the full path of the configuration file.
bEnvOverrides	true if environment variables are to be supported. The default is true.
bDefaultJvm	true if a platform-specific default JVM should be used as a default if no JVM is specified. The default is that a default JVM is used if nothing is specified.
fac	the trace facilities that are active. The default is that all trace facilities are enabled.
trace_level	the trace level at which they are active. The default is that only errors are traced.

◆ get_jvm_loader() [3/5]

static xmog_jvm_loader& xmog_jvm_loader::get_jvm_loader	(	const char *	filename,
		XMOGVERSION	vers,
		XMOGCONFIG	conf,
		XMOGVERSION	reserved0 = `NULL`,
		bool	bEnvOverrides = `true`,
		bool	bDefaultJvm = `true`,
		xmog_trace_facility	fac = `TraceAll`,
		xmog_trace_level	trace_level = `TraceErrors`
	)

static

The backwards-compatibility factory method that creates the JVM loader instance based on information from an old-style JunC++ion configuration file.

Old-style configuration files have the same format as an exported Windows registry and can contain multiple named configurations. An application selects one of these named configurations by providing a version and a name that uniquely identifies one configuration section in the file. In the new configuration file scheme, the configuration file itself contains all information that is required to select a particular section (and the format is XML, very much like a .NET config file). Use the other factory method that takes a filename as an argument to choose the new style of configuration.

Parameters

filename	the full path of the configuration file.
vers	the version number to be used for lookup in that file.
conf	the config name to be used for lookup in that file.
reserved0	An unused string. Always use NULL.
bEnvOverrides	true if environment variables are to be supported. The default is true.
bDefaultJvm	true if a platform-specific default JVM should be used as a default if no JVM is specified. The default is that a default JVM is used if nothing is specified.
fac	the trace facilities that are active. The default is that all trace facilities are enabled.
trace_level	the trace level at which they are active. The default is that only errors are traced.

◆ get_jvm_loader() [4/5]

static xmog_jvm_loader& xmog_jvm_loader::get_jvm_loader	(	int	argc,
		char *	argv[],
		bool	bEnvOverrides = `true`,
		bool	bDefaultJvm = `true`,
		xmog_trace_facility	fac = `TraceAll`,
		xmog_trace_level	trace_level = `TraceErrors`
	)

static

The factory method that creates the JVM loader instance based on commandline information.

Parameters

argc	the number of commandline arguments.
argv	the commandline arguments.
bEnvOverrides	true if environment variables are to be supported. The default is true.
bDefaultJvm	true if a platform-specific default JVM should be used as a default if no JVM is specified. The default is that a default JVM is used if nothing is specified.
fac	the trace facilities that are active. The default is that all trace facilities are enabled.
trace_level	the trace level at which they are active. The default is that only errors are traced.

◆ get_jvm_loader() [5/5]

static xmog_jvm_loader& xmog_jvm_loader::get_jvm_loader	(	XMOGVERSION	vers,
		XMOGCONFIG	conf,
		XMOGVERSION	reserved0 = `NULL`,
		bool	bEnvOverrides = `true`,
		bool	bDefaultJvm = `true`,
		xmog_trace_facility	fac = `TraceAll`,
		xmog_trace_level	trace_level = `TraceErrors`
	)

static

The factory method that creates the JVM loader instance based on information retrieved from the Windows registry (on Windows only) or a configuration file in a default location (on non-Windows platforms).

Parameters

vers	the version number to be used for lookup in that file.
conf	the config name to be used for lookup in that file.
reserved0	An unused string. Always use NULL.
bEnvOverrides	true if environment variables are to be supported. The default is true.
bDefaultJvm	true if a platform-specific default JVM should be used as a default if no JVM is specified. The default is that a default JVM is used if nothing is specified.
fac	the trace facilities that are active. The default is that all trace facilities are enabled.
trace_level	the trace level at which they are active. The default is that only errors are traced.

◆ get_jvm_loader_no_create()

static xmog_jvm_loader* xmog_jvm_loader::get_jvm_loader_no_create ( )

static

Returns a pointer to an already created xmog_jvm_loader or null if no loader has been created yet.

This method is primarily intended for internal use to prevent bootstrapping problems in the logging of property setters during loader creation. You can use it if you find it useful.

◆ getDefaultJvmPath()

static const char* xmog_jvm_loader::getDefaultJvmPath ( )

static

Returns the default path that could be used if no Jvm path has been set.

The string does not have to be freed because it is owned by the loader instance, not by the caller.

◆ getLoadResult()

jint xmog_jvm_loader::getLoadResult ( char ** pMsg = NULL )

Returns the error code from the load() operation.

This can be useful to diagnose load failures. In the case of a successful load(), this method returns 0.

◆ isInShutdownMode()

static bool xmog_jvm_loader::isInShutdownMode ( )

static

Returns true if we should not attempt to perform any more JVM-related activities.

We have triggered the unloading of the JVM or we have learned that the JVM is unloading/dead and we need to avoid doing JVM-related activities.

◆ load()

virtual xmog_jvm* xmog_jvm_loader::load ( bool bAcceptPreloadedJvm = true )

virtual

Attempts to load a JVM or connect to a remote server that has a JVM.

The optional argument can be used to allow the framework to work with a JVM that has been preloaded external to the process. It is not always possible to determine whether a JVM is already running in the process because one JVMs implementation of the test might not be able to discover another JVM.

Parameters

bAcceptPreloadedJvm true if a preloaded JVM should be used, false if we should fail when we detect a preloaded JVM. The default value is true.

◆ loadInProcess()

xmog_jvm* xmog_jvm_loader::loadInProcess ( bool bAcceptPreloadedJvm )

protected

Returns a newly loaded JVM instance based on the configured settings.

Parameters

bAcceptPreloadedJvm use a preloaded JVM if this argument is true and a JVM is already loaded into the process.

◆ loadOutOfProcess()

xmog_jvm* xmog_jvm_loader::loadOutOfProcess	(	bool	bAcceptPreloadedJvm,
		bool	bServer = `false`
	)

protected

Returns a newly loaded JVM instance that represents a client or a server connection to a shared JVM server.

Parameters

bAcceptPreloadedJvm	use a preloaded JVM if this argument is `true` and a JVM is already loaded into the process.
bServer	should always `false`.

◆ loadOutOfProcessClient()

xmog_jvm* xmog_jvm_loader::loadOutOfProcessClient ( bool bAcceptPreloadedJvm )

protected

Returns a newly loaded JVM instance that represents a client connection to a shared JVM server.

Parameters

bAcceptPreloadedJvm use a preloaded JVM if this argument is true and a JVM is already loaded into the process.

◆ loadOutOfProcessServer()

xmog_jvm* xmog_jvm_loader::loadOutOfProcessServer ( bool bAcceptPreloadedJvm )

protected

Returns a newly loaded JVM instance based on the configured settings.

Deprecated:: There is no server implementation.

◆ read()

virtual void xmog_jvm_loader::read	(	const char *	file,
		XMOGVERSION	vers = `NULL`,
		XMOGCONFIG	conf = `NULL`,
		XMOGVERSION	reserved0 = `NULL`
	)

virtual

Updates the instance's configuration data with information from the specified data source.

Parameters

file	the configuration file that is to be read. This value may be NULL on Windows, but then the optional vers and conf arguments need to be provided. In the NULL case, the runtime is going to attempt reading the initialization values from the registry. In the non-NULL case, the configuration file may either be an old-style JunC++ion configuration file or a new-style .NET configuration file. The runtime is going to pick one based on the first character of the configuration file. If it is an '<', the .NET XML format is going to be expected, otherwise the old JunC++ion format is going to be expected.
vers	an optional argument providing the old-style JunC++ion version number. This argument is required for registry-based and old-style JunC++ion based configuration. Always use "2.0" here.
conf	an optional argument providing the old-style JunC++ion configuration name. This argument is required for registry-based and old-style JunC++ion based configuration. It represents your application's unique configuration identifier that allows multiple JunC++ion-enabled applications to co-reside on one host.
reserved0	an optional argument that should always be NULL.

◆ registerConfigurationHook()

static void xmog_jvm_loader::registerConfigurationHook ( XMOG_CONFIG_HOOK configHook )

static

Registers a configuration hook (a method that is called during the creation of a JVM loader).

See a more detailed discussion at configuration hooks.

Parameters

configHook the configuration hook method that we wish to register.

◆ set_jvm()

virtual void xmog_jvm_loader::set_jvm ( xmog_jvm * jvm )

virtual

Sets a JVM into the loader.

This method fails if the loader already has a JVM in it. You should never have to call this method under normal circumstances.

◆ setConfigFile()

static void xmog_jvm_loader::setConfigFile	(	const char *	filename,
		XMOGVERSION	vers = `NULL`,
		XMOGCONFIG	conf = `NULL`,
		XMOGVERSION	reserved0 = `NULL`
	)

static

Specify the location of a config file and/or sub entries to be used when the runtime initializes.

This method allows a user to specify the location of the configuration file from which initialization arguments are to be retrieved without actually creating an xmog_jvm_loader yet. This might be useful if you want to give the user the chance to create the loader but you want to make sure that a particular configuration file or a particular named configuration is being used.

The optional arguments are only required if the old-style JunC++ion configfile format is used and not even then if the proxy types have been configured for a specific named configuration. In that case, the proxy type registration mechanism will take care of adding the named configuration to the list of used named configurations.

New-style JuggerNET configfiles contain all required information to select a particular configuration from the file, so no vers and conf arguments are necessary.

Parameters

filename	the full path of the configuration file. On Windows, `NULL` is a legal value that indicates that the registry should be used, but then the other arguments need to be specified.
vers	the version number to be used for lookup in that file. `NULL` is a legal value.
conf	the config name to be used for lookup in that file. `NULL` is a legal value.
reserved0	An unused string. Always use `NULL`.

◆ setJvmPath()

virtual void xmog_jvm_loader::setJvmPath ( const char * jvmPath )

virtual

Overrides the method from xmog_options.

Parameters

jvmPath the full path to the Java virtual machine library.

The documentation for this class was generated from the following file:

xmog_jvm_loader.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ xmog_jvm_loader() [1/5]

◆ xmog_jvm_loader() [2/5]

◆ xmog_jvm_loader() [3/5]

◆ xmog_jvm_loader() [4/5]

◆ xmog_jvm_loader() [5/5]

Member Function Documentation

◆ addExtensionDirectories()

◆ addVersionConfig()

◆ consolidateVersionConfigs()

◆ enterShutdownMode()

◆ get_jvm()

◆ get_jvm_loader() [1/5]

◆ get_jvm_loader() [2/5]

◆ get_jvm_loader() [3/5]

◆ get_jvm_loader() [4/5]

◆ get_jvm_loader() [5/5]

◆ get_jvm_loader_no_create()

◆ getDefaultJvmPath()

◆ getLoadResult()

◆ isInShutdownMode()

◆ load()

◆ loadInProcess()

◆ loadOutOfProcess()

◆ loadOutOfProcessClient()

◆ loadOutOfProcessServer()

◆ read()

◆ registerConfigurationHook()

◆ set_jvm()

◆ setConfigFile()

◆ setJvmPath()