com.neeve.server.embedded

Class EmbeddedXVM

java.lang.Object

com.neeve.server.embedded.EmbeddedXVM

public class EmbeddedXVM
extends Object

Wraps a SrvController to facilitate configuring and launching an embedded Talon XVM (aka Talon Server).

An EmbeddedXVM provides a thread of control for the xvm along with the requisite start() and shutdown() methods.

This class provides factory methods that allow the EmbeddedXVM to be created in a manner that is consistent with how the xvm would be configured and created using the non embedded Talon XVM Main, as well as factory methods that accept a pre configured or programmatically created SrvConfigDescriptor for the server.

Important Notes:
Creating multiple instances of an EmbeddedXVM or creating one after any other platform class has been loaded is inherently unreliable as by nature the intent of the Configurer is to not only seed the configuration repository with the server configuration but to also perform environment wide configuration that is used throughout the platform during static singleton initialization of shared components. As such it is not guaranteed that an EmbeddedXVM will behave exactly as one launched from the command line if the environment has been in any way altered prior to creation and start() of the EmbeddedXVM particularly if the Configurers for each xvm configure the environment in a different of conflicting fashion.

This class is not intended for use in production and is provided for use in testing situations. This class may be removed or altered in future releases, so users are encouraged to encapsulate this class to protect against changes until such time as its api has been stabliized.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	EmbeddedXVM.State Enumerates the various EmbeddedXVM states.

Method Summary

Methods

Modifier and Type	Method and Description
static EmbeddedXVM	create(Configurer configurer, String... args) Creates an embedded talon xvm using the provided configurer and optional arguments.
static EmbeddedXVM	create(Properties ddlProperties, String xvmName) Creates an embedded XVM.
static EmbeddedXVM	create(SrvConfigDescriptor configDescriptor) Creates an embedded talon xvm using the provided SrvConfigDescriptor.
static EmbeddedXVM	create(String... args) Bootstraps and creates an embedded talon xvm using the provided command line arguments.
static EmbeddedXVM	create(URL ddlConfig, String xvmName, Properties configProperties) Creates and embedded XVM using the provided DDL XML.
Object	getApplication(String appName) Gets an application loaded in this server.
SrvController	getServerController() Returns the underlying SrvController which provides access to its SrvAppManager
Throwable	getStartupError() Returns the error associated with a failed xvm start or null if the server started successfully, or failed without an associated exception.
EmbeddedXVM.State	getState() Gets the current xvm state.
void	shutdown() Shuts down the xvm (synchronously).
void	shutdown(boolean sync) Shuts down the xvm.
void	start() Starts the embedded talon xvm waiting until start up completes.
boolean	start(long timeout) Starts the embedded xvm, waiting for it to start.
EmbeddedXVM	verifyAppsLoaded(boolean val) Set whether the embedded XVM should verify whether apps successfully loaded on completion of start This check is on by default.
boolean	waitForStart(long timeout) Waits for the xvm to start.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static EmbeddedXVM create(Properties ddlProperties,
                 String xvmName)
                          throws Exception

Creates an embedded XVM.

WARNING: EmbeddedXVMs are intended for use only in testing scenarios. When launching more than one EmbeddedXVM in a JVM, the configuration bootstrapping of their environments cannot be guaranteed particularly in cases where their environment conflicts.

Parameters:

ddlProperties - The x-ddl configuration properties describing the system that contains the server.

xvmName - The name of the xvmName to create (which must be defined as a server in the ddlConfig). in the ddlConfig.

Returns:

An embedded XVM instance.

Throws:

Exception - If there is an error creating the EmbeddedXVM.

create

public static EmbeddedXVM create(URL ddlConfig,
                 String xvmName,
                 Properties configProperties)
                          throws Exception

Creates and embedded XVM using the provided DDL XML.

This method parses the provided DDL document and localizes the environment for the specified target XVM. The DDL is localized using the environment from UtlEnv and the provided configProperties passed in with precedence given to the provided properties.

This method resets the environment to its original state prior to launching unless the provided configProperties contains the value 'nv.server.embedded.suppressenvreset=true'. This helps to prevent enviroment variables set by previous EmbeddedXVMs from affecting this XVM launch.

WARNING: EmbeddedXVMs are intended for use only in testing scenarios. When launching more than one EmbeddedXVM in a JVM, the configuration bootstrapping of their environments cannot be guaranteed particularly in cases where their environment conflicts.

Parameters:

ddlConfig - The x-ddl configuration document describing the system that contains the server.

xvmName - The name of the xvmName to create (which must be defined as a server in the ddlConfig).

configProperties - The set of configuration properties to use for DDL substitution and DDL overlay properties. in the ddlConfig. These values will override any elements sourced from UtlEnv.

Returns:

An embedded XVM instance.

Throws:

Exception - If there is an error creating the EmbeddedXVM.

create

public static EmbeddedXVM create(String... args)
                          throws Exception

Bootstraps and creates an embedded talon xvm using the provided command line arguments.

This method allows creation of a Talon server using the same arguments that would be used to launch a non embedded server using the Talon Server Main. Specifically this method:

Attempts to load a bootstrap Configurer via Main.loadBootstrapConfigurer()
• If a configurer is found invoke the Configurer.configure(String[]) method with the supplied arguments to allow it to seed the configuration repository via VMConfigurer.
• If the --name arg is present, will create a SrvController using the embedded

  WARNING: EmbeddedXVMs are intended for use only in testing scenarios. When launching more than one EmbeddedXVM in a JVM, the configuration bootstrapping of their environments cannot be guaranteed particularly in cases where their environment conflicts.

Parameters:

args - The same arguments that would be passed on the command line when launching Main.main(String[]). It is possible to pass in "--help" to pring a listing of valid arguments.

Returns:

A new EmbeddedXVM.

Throws:

Exception - If there is an error creating the embedded server.

See Also:

Main, SrvController

Threading:

this call is not safe for access by multiple threads concurrently.

create

public static EmbeddedXVM create(SrvConfigDescriptor configDescriptor)
                          throws Exception

Creates an embedded talon xvm using the provided SrvConfigDescriptor.

Returns:

A new EmbeddedXVM.

Throws:

Exception - If there is an error creating the embedded server.

Threading:

this call is safe for concurrent access by multiple threads.

create

public static EmbeddedXVM create(Configurer configurer,
                 String... args)
                          throws Exception

Creates an embedded talon xvm using the provided configurer and optional arguments.

This method is equivalent to create(String...) except that the bootstrap Configurer invoked is the one supplied here. If the Configurer is null, no bootstrap configuration is performed.

WARNING: EmbeddedXVMs are intended for use only in testing scenarios. When launching more than one EmbeddedXVM in a JVM, the configuration bootstrapping of their environments cannot be guaranteed particularly in cases where their environment conflicts.

Parameters:

configurer - The Bootstrap Configurer to use for seeding the server configuration.

args - The same arguments that would be passed on the command line when launching Main.main(String[]). It is possible to pass in "--help" to pring a listing of valid arguments.

Returns:

A new EmbeddedXVM.

Throws:

Exception - If there is an error creating the embedded server.

Threading:

this call is not safe for access by multiple threads concurrently.

verifyAppsLoaded

public EmbeddedXVM verifyAppsLoaded(boolean val)

Set whether the embedded XVM should verify whether apps successfully loaded on completion of start

This check is on by default. Use this method to change whether the check should be performed or not

Throws:

IllegalStateException - Thrown if this method is invoked in any state other than the Init state

start

public boolean start(long timeout)
              throws TimeoutException,
                     Throwable

Starts the embedded xvm, waiting for it to start.

When working with multiple embedded servers that employ separate Configurers it is generally not a good idea to start servers in parallel to avoid separate configurations from stepping on one another during the startup phase.

If this call throws an Exception, it is incumbent on the caller to call shutdown().

Parameters:

timeout - The time in seconds to wait for the server to start. A value of -1 means wait indefinitely, 0 means don't wait at all, otherwise wait the given number of seconds

Returns:

true if the server is EmbeddedXVM.State.Started, or false if it did not start in the allotted time and is still EmbeddedXVM.State.Starting

Throws:

IllegalStateException - If the server was already started.

InterruptedException - If the thread is interrupted waiting for the server to start.

Throwable - If the server fails to start

TimeoutException

Threading:

this call is not safe for concurrent access by multiple threads.

start

public void start()
           throws Throwable

Starts the embedded talon xvm waiting until start up completes.

This id equivalent to calling start(long) with a value of -1

Throws:

IllegalStateException - If the server was already started.

Throwable

Threading:

this call is not safe for concurrent access by multiple threads.

getStartupError

public Throwable getStartupError()

Returns the error associated with a failed xvm start or null if the server started successfully, or failed without an associated exception.

Returns:

The startup failure for the xvm if it did not start successfully.

Threading:

this call is safe for access by multiple threads.

shutdown

public void shutdown()

Shuts down the xvm (synchronously).

Threading:

this call is not safe for concurrent access by multiple threads. Furthermore, it is not safe to call this from any thread that must exit prior to server shutdown.

shutdown

public void shutdown(boolean sync)

Shuts down the xvm.

Parameters:

sync - Whether or not to synchronously shutdown the server. It is not safe to set this value to true when called from any thread that must exit prior to server shutdown.

Threading:

this call is not safe for concurrent access by multiple threads.

getState

public EmbeddedXVM.State getState()

Gets the current xvm state.

Returns:

The current xvm state.

Threading:

this call is safe for access by multiple threads.

waitForStart

public boolean waitForStart(long timeout)
                     throws Throwable

Waits for the xvm to start.

Parameters:

timeout - The time in seconds to wait for the server to start. A value of -1 means wait indefinitely, 0 means don't wait at all, otherwise wait the given number of seconds

Returns:

false if the after waiting the allotted timeout the xvm is still in EmbeddedXVM.State.Starting

Throws:

IllegalStateException - If the xvm has not been started or has been shutdown.

InterruptedException - If the thread is interrupted waiting for the xvm to start.

Throwable - thrown if there is an error in xvm startup or the server was shutdown.

Threading:

this call is safe for access by multiple threads.

getServerController

public SrvController getServerController()

Returns the underlying SrvController which provides access to its SrvAppManager

Returns:

The underling SrvController.

Threading:

this call is safe for access by multiple threads.

getApplication

public Object getApplication(String appName)

Gets an application loaded in this server.

Parameters:

appName - The name of the application.

Returns:

The application or null, if no application with the given name is loaded.