#include <xmog_jvm_loader.h>
Inheritance diagram for xmog_jvm_loader:
Public Types | |
| typedef void(XMOG_CALLING_CONVENTION * | XMOG_CONFIG_HOOK )(void *pLoader, int when) |
| A typedef for registration hooks. | |
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. | |
| virtual xmog_jvm * | get_jvm () |
| Returns the JVM wrapper instance if one already exists. | |
| virtual void | set_jvm (xmog_jvm *jvm) |
| Sets a JVM into the loader. | |
| jint | getLoadResult (char **pMsg=NULL) |
| Returns the error code from the load() operation. | |
| 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. | |
| 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. | |
| bool | getEnvironmentOverrides () const |
Returns true if environment variables can override configured settings. | |
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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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). | |
| 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. | |
| static const char * | getDefaultJvmPath () |
| Returns the default path that could be used if no Jvm path has been set. | |
| static bool | isInShutdownMode () |
| Returns true if we should not attempt to perform any more JVM-related activities. | |
| static void | enterShutdownMode () |
| Enters shutdownmode. | |
| static void | addVersionConfig (const char *vers, const char *config) |
| Adds a version/config pair to the list of configurations. | |
| static void | registerConfigurationHook (XMOG_CONFIG_HOOK configHook) |
| Registers a configuration hook (a method that is called during the creation of a JVM loader). | |
| 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. | |
| 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. | |
| 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. | |
| xmog_jvm_loader (int argc, char *argv[], bool bEnvOverrides, bool bDefaultJvm, xmog_trace_facility fac, xmog_trace_level) | |
| The constructor that parses a commandline. | |
| 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. | |
| 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. | |
| xmog_jvm * | loadOutOfProcessClient (bool bAcceptPreloadedJvm) |
| Returns a newly loaded JVM instance that represents a client connection to a shared JVM server. | |
| xmog_jvm * | loadOutOfProcessServer (bool bAcceptPreloadedJvm) |
| Returns a newly loaded JVM instance based on the configured settings. | |
| 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. | |
| void | consolidateVersionConfigs () |
| Consolidates select options from multiple named configurations into the JVM loader instance. | |
| void | addExtensionDirectories () |
| Adds the configured JRE's "ext" directory to the JVM configuration's extension directories. | |
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:
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.
|
||||||||||||||||||||
|
The default constructor.
|
|
||||||||||||||||||||||||
|
The constructor allowing the specification of a configuration file.
|
|
||||||||||||||||||||||||||||||||||||
|
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.
|
|
||||||||||||||||||||||||||||
|
The constructor that parses a commandline.
|
|
||||||||||||||||||||||||||||||||
|
The constructor allowing the specification of a registry section. This constructor is used by the legacy config file (or registry) mechanism of JunC++ion.
|
|
|
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. |
|
||||||||||||
|
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. |
|
|
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:
|
|
|
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. |
|
|
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 |
|
||||||||||||||||||||||||||||||||
|
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).
|
|
||||||||||||||||||||||||||||
|
The factory method that creates the JVM loader instance based on commandline information.
|
|
||||||||||||||||||||||||
|
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.
|
|
||||||||||||||||||||||||||||||||||||
|
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.
|
|
||||||||||||||||||||
|
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.
|
|
|
Returns a pointer to an already created xmog_jvm_loader or 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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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.
|
|
|
Returns a newly loaded JVM instance based on the configured settings.
|
|
||||||||||||
|
Returns a newly loaded JVM instance that represents a client or a server connection to a shared JVM server.
|
|
|
Returns a newly loaded JVM instance that represents a client connection to a shared JVM server.
|
|
|
Returns a newly loaded JVM instance based on the configured settings.
|
|
||||||||||||||||||||
|
Updates the instance's configuration data with information from the specified data source.
|
|
|
Registers a configuration hook (a method that is called during the creation of a JVM loader). See a more detailed discussion at configuration hooks.
|
|
|
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. |
|
||||||||||||||||||||
|
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
|
|
|
Overrides the method from xmog_options.
|
1.4.1