xmog_options Class Reference
[Runtime Configuration]

This class wraps around options that govern the overall behavior of the runtime library with respect to logging, tracing, errorhandling, etc. More...

#include <xmog_options.h>

Inheritance diagram for xmog_options:

[legend]Collaboration diagram for xmog_options:

[legend]List of all members.

Public Member Functions
virtual int	readOptions (const char *file, XMOGVERSION vers=NULL, XMOGCONFIG conf=NULL, XMOGVERSION reserved0=NULL)
	Reads a configuration file and initializes the instance with the found settings.
virtual void	setCOMExceptionMessages (const char *ce)
	Sets the flag controlling whether COM exception support should be turned on.
virtual void	setCOMExceptionMessages (bool ce)
	Sets the flag controlling whether COM exception support should be turned on.
virtual bool	getCOMExceptionMessages ()
	Returns whether COM exception support is turned on.
virtual void	setUseCodemeshSecurityManager (const char *ce)
	Sets the flag controlling whether a Codemesh SecurityManager should be used.
virtual void	setUseCodemeshSecurityManager (bool ce)
	Sets the flag controlling whether a Codemesh SecurityManager should be used.
virtual bool	getUseCodemeshSecurityManager ()
	Returns whether the Codemesh security manager should be used.
virtual void	setJvmPath (const char *jvmPath)
	Sets the JVM path that is to be used.
virtual char *	getJvmPath ()
	Returns the JVM path used by the in-process JNI implementation.
virtual void	setNoshutdownProcessing (bool noshut)
	Sets the shutdown policy.
virtual void	setNoshutdownProcessing (const char *noshut)
	Sets the shutdown policy.
virtual bool	getNoshutdownProcessing ()
	Returns the shutdwon policy.
virtual void	setTracing (xmog_trace_facility fac, int level)
	Sets the tracing level for a given tracing category.
virtual void	setTracing (xmog_trace_facility fac, xmog_trace_level level)
	Sets the tracing level for a given tracing category.
virtual void	setTracing (xmog_trace_facility fac, const char *level)
	Sets the tracing level for a given tracing category.
virtual void	setTracing (const char *facAndLevel)
	Sets the tracing level for a given tracing category.
virtual xmog_trace_level	getTracing (xmog_trace_facility fac)
	Returns the tracing level for a given category.
virtual void	setTraceFile (const char *traceFile)
	Sets the trace file.
virtual char *	getTraceFile ()
	Returns the name of the trace file.
virtual void	setTraceMethod (const char *traceMethod)
	Sets the trace method.
virtual void	setTraceMethod (XMOG_TRACE traceMethod)
	Sets the trace method.
virtual XMOG_TRACE	getTraceMethod ()
	Returns the trace method.
virtual void	trace (xmog_trace_facility fac, xmog_trace_level level, const char *format,...)
	Trace a certain message belonging to a certain category at a certain level.
virtual void	trace (int fac, xmog_trace_level level, const char *format,...)
	Trace a certain message belonging to a certain category at a certain level.
virtual void	setDefaultEncoding (const char *enc)
	Sets the default encoding that is used by newly created threads that are attached to the JVM.
virtual char *	getDefaultEncoding ()
	Returns the name of the default encoding that is to be used for the new JVM.
virtual void	setExceptionPolicy (const char *pol)
	Sets the errorhandling policy.
virtual void	setExceptionPolicy (xmog_exception_policy pol, XMOG_ECB exccb=0)
	Sets the errorhandling policy.
virtual xmog_exception_policy	getExceptionPolicy ()
	Returns the errorhandling policy.
virtual void	setExceptionCallback (const char *exccb)
	Sets the errorhandling callback method.
virtual void	setExceptionCallback (XMOG_ECB exccb)
	Sets the errorhandling callback method.
virtual XMOG_ECB	getExceptionCallback ()
	Returns the errorhandling callback method.
virtual void	setRemote (bool remote)
	Sets the remote flag.
virtual void	setRemote (const char *remote)
	Sets the remote flag.
virtual bool	getRemote ()
	Returns the remote flag.
virtual void	setServer (bool server)
	Sets the server flag.
virtual bool	getServer ()
	Returns the value of the server flag.
void	printJvmPathAndExit ()
	Prints the configured JvmPath to stdout and exits.
char *	getLdLibraryPath ()
	Returns a path that is proper for the configured JVM.
void	setLdLibraryPath (const char *path)
	Sets the environment variable that is responsible for specifying the path on which shared libraries are searched for.
void	printLdLibraryPathAndExit ()
	Prints to stdout the PATH components that are probably required to be on the platform loader's library search path and then exits.
Protected Member Functions
	xmog_options (bool bEnvOverrides=true)
	Creates an xmog_options instance that might be initialized from the environment.
	xmog_options (const char *filename, bool bEnvOverrides=true)
	Creates an xmog_options instance that might be initialized from a file and/or the environment.
	xmog_options (const char *filename, XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0, bool bEnvOverrides=true)
	Creates an xmog_options instance that might be initialized from a file and/or the environment.
	xmog_options (XMOGVERSION vers, XMOGCONFIG conf, XMOGVERSION reserved0, bool bEnvOverrides=true)
	Creates an xmog_options instance that might be initialized from a file the registry and/or the environment.
	xmog_options (int argc, char *argv[], bool bEnvOverrides=true)
	Creates an xmog_options instance that might be initialized from command line arguments and/or the environment.
virtual	~xmog_options ()
	Cleans up behind the instance.
void	init ()
	Initializes the instance.
void	env_override ()
	Initializes the options data from the environment variables.
void	reset ()
	Resets the instance to its initial defaults.

---

Detailed Description

This class wraps around options that govern the overall behavior of the runtime library with respect to logging, tracing, errorhandling, etc.

This class supports the following properties:

Setting	File or Registry	CLI	Environment	Description
Special COM support	COMExceptionMessages	-cem	XMOG_CEM	Enable special handling of exceptions that makes error reporting easier for COM clients. This feature is usually only used from .NET via generated C# bindings.
Default Encoding	DefaultEncoding	-enc	XMOG_DEFAULT_ENCODING	The default character set that is used for conversions between Java strings and native strings, for example "US-ASCII". See also: String Handling
Errorhandling policy	ExceptionHandling	-exc	XMOG_EXCEPTION_POLICY	The default errorhandling policy, for example "TypedException". See also: Error Handling
Errorhandling callback	ExceptionCallback	-exccb	XMOG_EXCEPTION_CALLBACK	The callback to be used for the "ExceptionCallback" policy.
JVM	RuntimeLib	-jvm	XMOG_JVM_PATH	The runtime library to be used.
Shutdown processing	NoShutdown	-noshut	XMOG_NO_SHUT	true if normal shutdown processing is to be suppressed.
Remote	Remote	-remote	XMOG_REMOTE	true if a remote connection to a shared JVM is to be used, false if in-process JNI should be used.
Custom trace file	TraceFile	-tracefile	XMOG_TRACE_FILE	The file to which all tracing output is sent.
Tracing level at which messages are logged	TraceLevel	-tracelevel	XMOG_TRACE_LEVEL	The tracelevel for all trace facilities. Use the string form of the value, for example TraceInfo or TraceVerbose.
Custom trace method	TraceMethod	-tracemethod	XMOG_TRACE_METHOD	The function to be used for tracing calls.
Security Manager	UseCodemeshSecurityManager	-cmsm	XMOG_USE_CODEMESH_SECURITY_MANAGER	This feature causes Codemesh's security manager to be used in place of the configured one. The Codemesh security manager grants several privileges required by the runtime without you having to worry about it. It delegates other checks to the configured security manager. See also: Security

---

Constructor & Destructor Documentation

xmog_options::xmog_options (  bool  bEnvOverrides = true  )  [protected]

Creates an xmog_options instance that might be initialized from the environment. Parameters: bEnvOverrides  true if environment variables are taken into account.

xmog_options::xmog_options (  const char *  filename, bool  bEnvOverrides = true )  [protected]

Creates an xmog_options instance that might be initialized from a file and/or the environment. Parameters: filename  the name of the configuration file which contains runtime configuration settings. bEnvOverrides  true if environment variables are taken into account.

xmog_options::xmog_options (  const char *  filename, XMOGVERSION  vers, XMOGCONFIG  conf, XMOGVERSION  reserved0, bool  bEnvOverrides = true )  [protected]

Creates an xmog_options instance that might be initialized from a file and/or the environment. This particular method takes old-style section selectors as input, giving it all information required to deal with old JunC++ion-style configuration files. Parameters: filename  the name of the configuration file which contains runtime configuration settings. vers  the version string we're looking for in the configfile. conf  the configuration name string we're looking for in the configfile. reserved0  should always be NULL. bEnvOverrides  true if environment variables are taken into account.

xmog_options::xmog_options (  XMOGVERSION  vers, XMOGCONFIG  conf, XMOGVERSION  reserved0, bool  bEnvOverrides = true )  [protected]

Creates an xmog_options instance that might be initialized from a file the registry and/or the environment. This particular method takes old-style section selectors as input, giving it all information required to deal with the old JunC++ion-style configuration files or registry settings. Parameters: vers  the version string we're looking for in the configfile. conf  the configuration name string we're looking for in the configfile. reserved0  should always be NULL. bEnvOverrides  true if environment variables are taken into account.

xmog_options::xmog_options (  int  argc, char *  argv[], bool  bEnvOverrides = true )  [protected]

Creates an xmog_options instance that might be initialized from command line arguments and/or the environment. Parameters: argc  the number of arguments. argv  an array of string arguments. bEnvOverrides  true if environment variables are taken into account.

---

Member Function Documentation

virtual bool xmog_options::getCOMExceptionMessages (   )  [virtual]

Returns whether COM exception support is turned on. This method is a support method for the .NET bindings.

virtual char* xmog_options::getDefaultEncoding (   )  [virtual]

Returns the name of the default encoding that is to be used for the new JVM. See also: setDefaultEncoding(const char*)

char* xmog_options::getLdLibraryPath (   )

Returns a path that is proper for the configured JVM. The caller is responsible for freeing the returned string.

virtual bool xmog_options::getServer (   )  [virtual]

Returns the value of the server flag. Deprecated:

virtual xmog_trace_level xmog_options::getTracing (  xmog_trace_facility  fac  )  [virtual]

Returns the tracing level for a given category. Parameters: fac  the tracing facility for which we wish to know the current minimum level.

void xmog_options::printJvmPathAndExit (   )

Prints the configured JvmPath to stdout and exits. This function is useful to query an application's configured JVM and set up the LD_LIBRARY_PATH (LIBPATH,...) if the builtin function for that purpose does not work with the configured JVM.

virtual int xmog_options::readOptions (  const char *  file, XMOGVERSION  vers = NULL, XMOGCONFIG  conf = NULL, XMOGVERSION  reserved0 = NULL )  [virtual]

Reads a configuration file and initializes the instance with the found settings. Parameters: file  the name of the configuration file which contains runtime configuration settings. vers  the version string we're looking for in the configfile. conf  the configuration name string we're looking for in the configfile. reserved0  should always be NULL. Returns: 0 on success, negative value on failure.

virtual void xmog_options::setCOMExceptionMessages (  bool  ce  )  [virtual]

Sets the flag controlling whether COM exception support should be turned on. This method is a support method for the .NET bindings. Parameters: ce  true if COM exception support is to be turned on.

virtual void xmog_options::setCOMExceptionMessages (  const char *  ce  )  [virtual]

Sets the flag controlling whether COM exception support should be turned on. This method is a support method for the .NET bindings. Parameters: ce  "true" if COM exception support is to be turned on.

virtual void xmog_options::setDefaultEncoding (  const char *  enc  )  [virtual]

Sets the default encoding that is used by newly created threads that are attached to the JVM. Parameters: enc  the encoding to be used. The following encodings are supported by all JVMs: US-ASCII, ISO-8859-1, UTF-8, UTF-16BE, UTF-16LE, and UTF-16. Other encodings are supported as well.

virtual void xmog_options::setJvmPath (  const char *  jvmPath  )  [virtual]

Sets the JVM path that is to be used. Parameters: jvmPath  the path to the JVM that is to be used by the native process if in-process JNI is desired.

void xmog_options::setLdLibraryPath (  const char *  path  )

Sets the environment variable that is responsible for specifying the path on which shared libraries are searched for. This function is not the corresponding function to getLdLibraryPath(). This function allows the specification of an arbitrary path whereas the getLdLibraryPath() function returns the union of the already configured path and the directories required for the currently configured JVM.

virtual void xmog_options::setNoshutdownProcessing (  const char *  noshut  )  [virtual]

Sets the shutdown policy. Sometimes the operating system unloads the JVM before the process has had a chance to call all the object destructors. In that case, the process will crash on exit. Setting the noshutdown flag to true will prevent the destructors from executing and prevent the crash. Parameters: noshut  "true" to suppress JVM cleanup during shutdown processing, "false" otherwise.

virtual void xmog_options::setNoshutdownProcessing (  bool  noshut  )  [virtual]

Sets the shutdown policy. Sometimes the operating system unloads the JVM before the process has had a chance to call all the object destructors. In that case, the process will crash on exit. Setting the noshutdown flag to true will prevent the destructors from executing and prevent the crash. Parameters: noshut  "true" to suppress JVM cleanup during shutdown processing, "false" otherwise.

virtual void xmog_options::setRemote (  const char *  remote  )  [virtual]

Sets the remote flag. Use true to use the remote connection settings to attempt connecting to an out-of-process JVM, false for in-process JNI. Parameters: remote  "true" if remote execution is desired, "false" otherwise.

virtual void xmog_options::setRemote (  bool  remote  )  [virtual]

Sets the remote flag. Use true to use the remote connection settings to attempt connecting to an out-of-process JVM, false for in-process JNI. Parameters: remote  true if remote execution is desired, false otherwise.

virtual void xmog_options::setServer (  bool  server  )  [virtual]

Sets the server flag. Deprecated:

virtual void xmog_options::setTraceFile (  const char *  traceFile  )  [virtual]

Sets the trace file. Allows tracing output to be rerouted to a file that is specified by name. The strings "stdout" and "stderr" refer to the console output and error output streams and are treated specially. NULL will simply close a possibly open tracing stream and not open a new one. Parameters: traceFile  the trace file to which we're printing trace messages.

virtual void xmog_options::setTracing (  const char *  facAndLevel  )  [virtual]

Sets the tracing level for a given tracing category. This method can be used to set the threshold level above which tracing messages will be used for a given facility. Parameters: facAndLevel  the tracing facility and level.

virtual void xmog_options::setTracing (  xmog_trace_facility  fac, const char *  level )  [virtual]

Sets the tracing level for a given tracing category. This method can be used to set the threshold level above which tracing messages will be used for a given facility. Parameters: fac  the tracing facility for which we're setting the minimum level. level  the minimum level of importance that we're tracing.

virtual void xmog_options::setTracing (  xmog_trace_facility  fac, xmog_trace_level  level )  [virtual]

Sets the tracing level for a given tracing category. This method can be used to set the threshold level above which tracing messages will be used for a given facility. Parameters: fac  the tracing facility for which we're setting the minimum level. level  the minimum level of importance that we're tracing.

virtual void xmog_options::setTracing (  xmog_trace_facility  fac, int  level )  [virtual]

Sets the tracing level for a given tracing category. This method can be used to set the threshold level above which tracing messages will be used for a given facility. Parameters: fac  the tracing facility for which we're setting the minimum level. level  the minimum level of importance that we're tracing.

virtual void xmog_options::setUseCodemeshSecurityManager (  bool  ce  )  [virtual]

Sets the flag controlling whether a Codemesh SecurityManager should be used. Parameters: ce  true if the Codemesh security manager should be used.

virtual void xmog_options::setUseCodemeshSecurityManager (  const char *  ce  )  [virtual]

Sets the flag controlling whether a Codemesh SecurityManager should be used. Parameters: ce  "true" if the Codemesh security manager should be used.

virtual void xmog_options::trace (  int  fac, xmog_trace_level  level, const char *  format,   ... )  [virtual]

Trace a certain message belonging to a certain category at a certain level. Parameters: fac  the trace facility(s) for which this message is relevant. level  the trace level of this message. format  the message or format string (in printf style). Implements xmog_tracer.

virtual void xmog_options::trace (  xmog_trace_facility  fac, xmog_trace_level  level, const char *  format,   ... )  [virtual]

Trace a certain message belonging to a certain category at a certain level. Parameters: fac  the trace facility for which this message is relevant. level  the trace level of this message. format  the message or format string (in printf style). Implements xmog_tracer.

---

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

• xmog_options.h

---