org.wildfly.swarm

Class Swarm

java.lang.Object

org.wildfly.swarm.Swarm

public class Swarm
extends Object

Default main(...) if an application does not provide one.

This simply constructs a default container, starts it and performs a default deployment. Typically only useful for barren WAR applications.

If providing their own main(...), then the following needs to be known:

• Any usage of java.util.logging may only follow the initial constructor of new Swarm().
• While this object may appear to be thread-safe, it does rely on general static instances for some facilities. Therefore, it should not be instantiated several times concurrently.
• It can be instantiated multiple times serially, as long as one instance is disposed before another is created and used. This limitation may be removed in a future version, if required.

If using this class either directly or implicit as a main(...), certain command-line facilities are available. If used directly, the user should pass the String...args from his own main(...) to the constructor of this class if these command-line facilities are desired.

Many internal aspects of the runtime container may be configured using the Java APIs for various fractions, XML configuration files, YAML configuration files, and Java system properties.

Configuration ordering works as follows: Fractions configured through an XML configuration file takes precedence over the same fraction configured through the Java API. YAML or system properties may override portions or attributes of fractions defined either way. A system property override binds more strongly than YAML configuration.

Author:

Bob McWhirter, Ken Finnigan

Field Summary

Fields

Modifier and Type	Field and Description
static String	APPLICATION_MODULE_NAME
static Swarm	INSTANCE

Constructor Summary

Constructors

Constructor and Description
Swarm() Construct a new, un-started container.
Swarm(boolean debugBootstrap) Construct a new, un-started container.
Swarm(boolean debugBootstrap, Properties properties, Map<String,String> environment, String... args)
Swarm(boolean debug, Properties properties, String... args)
Swarm(boolean debugBootstrap, String... args) Construct a new, un-started container, configured using command-line arguments.
Swarm(Properties properties, Map<String,String> environment, String... args)
Swarm(Properties properties, String... args)
Swarm(String... args) Construct a new, un-started container, configured using command-line arguments.

Method Summary

Modifier and Type	Method and Description
static List<JavaArchive>	allArtifacts() Retrieve all dependency artifacts for the user's project.
static JavaArchive	artifact(String gav) Retrieve an artifact that was part of the original build using a full or simplified Maven GAV specifier.
static JavaArchive	artifact(String gav, String asName) Retrieve an artifact that was part of the original build using a full or simplified Maven GAV specifier, returning an archive with a specified name.
Swarm	component(Class<?> cls)
ConfigView	configView() Retrieve the configuration view.
<any>	createDefaultDeployment() Retrieve the default ShrinkWrap deployment.
Swarm	deploy() Perform a default deployment.
Swarm	deploy(<any> deployment) Deploy an archive.
Swarm	fraction(Fraction fraction) Add a fraction to the container.
CommandLine	getCommandLine() Retrieve the parsed command-line from this instance.
static void	main(String... args) Main entry-point if a user does not specify a custom main(...)-containing class.
Swarm	outboundSocketBinding(String socketBindingGroup, OutboundSocketBinding binding) Add an outbound socket-binding to the container.
void	setArgs(String... args) Pass the effective command-line arguments to this instance.
Swarm	socketBinding(String socketBindingGroup, SocketBinding binding) Add an inbound socket-binding to the container.
StageConfig	stageConfig() Deprecated.
Swarm	start() Start the container.
Swarm	start(<any> deployment) Start the container with a deployment.
Swarm	stop() Stop the container, first undeploying all deployments.
static void	stopMain()
Swarm	withConfig(URL url)
Swarm	withProfile(String name)
Swarm	withProperty(String name, String value)
Swarm	withXmlConfig(URL url) Specify an XML configuration file (in usual WildFly standalone.xml) format.

Methods inherited from class java.lang.Object

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

Field Detail

INSTANCE

public static Swarm INSTANCE

APPLICATION_MODULE_NAME

public static final String APPLICATION_MODULE_NAME

See Also:

Constant Field Values

Constructor Detail

Swarm

public Swarm()
      throws Exception

Construct a new, un-started container.

Throws:

Exception - If an error occurs performing classloading and initialization magic.

Swarm

public Swarm(boolean debugBootstrap)
      throws Exception

Construct a new, un-started container.

Parameters:

debugBootstrap - - flag to indicate if the module layer should be put into bootstrap debug mode. Same as the jboss-module -debuglog mode which enables trace logging to System.out during the initial bootstrap of the module layer.

Throws:

Exception - If an error occurs performing classloading and initialization magic.

Swarm

public Swarm(String... args)
      throws Exception

Construct a new, un-started container, configured using command-line arguments.

Parameters:

args - The command-line arguments arguments

Throws:

Exception - If an error occurs performing classloading and initialization magic.

Swarm

public Swarm(boolean debugBootstrap,
             String... args)
      throws Exception

Construct a new, un-started container, configured using command-line arguments.

Parameters:

debugBootstrap - - flag to indicate if the module layer should be put into bootstrap debug mode. Same as the jboss-module -debuglog mode which enables trace logging to System.out during the initial bootstrap of the module layer.

args - The command-line arguments arguments

Throws:

Exception - If an error occurs performing classloading and initialization magic.

Swarm

public Swarm(Properties properties,
             String... args)
      throws Exception

Throws:

Exception

Swarm

public Swarm(boolean debug,
             Properties properties,
             String... args)
      throws Exception

Throws:

Exception

Swarm

public Swarm(Properties properties,
             Map<String,String> environment,
             String... args)
      throws Exception

Throws:

Exception

Swarm

public Swarm(boolean debugBootstrap,
             Properties properties,
             Map<String,String> environment,
             String... args)
      throws Exception

Throws:

Exception

Method Detail

getCommandLine

public CommandLine getCommandLine()

Retrieve the parsed command-line from this instance.

This method is only applicable if the String...args was passed through the constructor or setArgs(String...) was called to provide the command-line arguments.

Returns:

The parsed command-line.

setArgs

public void setArgs(String... args)

Pass the effective command-line arguments to this instance.

Parameters:

args - The arguments.

withXmlConfig

public Swarm withXmlConfig(URL url)

Specify an XML configuration file (in usual WildFly standalone.xml) format.

Usage of an XML configuration file is not exclusive with other configuration methods.

Parameters:

url - The URL of the XML configuration file.

Returns:

This instance.

See Also:

withConfig(URL)

withConfig

public Swarm withConfig(URL url)
                 throws IOException

Throws:

IOException

withProfile

public Swarm withProfile(String name)

withProperty

public Swarm withProperty(String name,
                          String value)

fraction

public Swarm fraction(Fraction fraction)

Add a fraction to the container.

Parameters:

fraction - The fraction to add.

Returns:

The container.

component

public Swarm component(Class<?> cls)

outboundSocketBinding

public Swarm outboundSocketBinding(String socketBindingGroup,
                                   OutboundSocketBinding binding)

Add an outbound socket-binding to the container.

In the event the specified socketBindingGroup does not exist, the socket-binding will be completely ignored.

TODO fix the above-mentioned issue.

Parameters:

socketBindingGroup - The name of the socket-binding group to attach a binding to.

binding - The outbound socket-binding to add.

Returns:

This container.

socketBinding

public Swarm socketBinding(String socketBindingGroup,
                           SocketBinding binding)

Add an inbound socket-binding to the container.

In the even the specified socketBindingGroup does no exist, the socket-binding will be completely ignored.

TODO fix the above-mentioned issue.

Parameters:

socketBindingGroup - The name of the socket-binding group to attach a binding to.

binding - The inbound socket-binding to add.

Returns:

This container.

start

public Swarm start()
            throws Exception

Start the container.

This is a blocking call, which guarateens that when it returns without error, the container is fully started.

Returns:

The container.

Throws:

Exception - if an error occurs.

start

public Swarm start(<any> deployment)
            throws Exception

Start the container with a deployment.

Effectively calls start().deploy(deployment)

Parameters:

deployment - The deployment to deploy.

Returns:

The container.

Throws:

Exception - if an error occurs.

See Also:

start(), #deploy(Archive)

stop

public Swarm stop()
           throws Exception

Stop the container, first undeploying all deployments.

Returns:

THe container.

Throws:

Exception - If an error occurs.

deploy

public Swarm deploy()
             throws IllegalStateException,
                    DeploymentException

Perform a default deployment.

For regular uberjars, it is effectively a short-cut for deploy(swarm.createDefaultDeployment()), deploying the baked-in deployment.

For hollow uberjars, it deploys whatever deployments were passed through the command-line, as none are baked-in.

Returns:

The container.

Throws:

DeploymentException - if an error occurs.

IllegalStateException - if the container has not already been started.

See Also:

Swarm(String...), setArgs(String...), #deploy(Archive), createDefaultDeployment()

deploy

public Swarm deploy(<any> deployment)
             throws Exception

Deploy an archive.

Parameters:

deployment - The ShrinkWrap archive to deploy.

Returns:

The container.

Throws:

DeploymentException - if an error occurs.

Exception

createDefaultDeployment

public <any> createDefaultDeployment()
                              throws Exception

Retrieve the default ShrinkWrap deployment.

Returns:

The default deployment, unmodified.

Throws:

Exception

main

public static void main(String... args)
                 throws Exception

Main entry-point if a user does not specify a custom main(...)-containing class.

The default behaviour of this main(...) is to start the container entirely with defaults and deploy the default deployment.

Parameters:

args - The command-line arguments from the invocation.

Throws:

Exception - if an error occurs.

stopMain

public static void stopMain()
                     throws Exception

Throws:

Exception

artifact

public static JavaArchive artifact(String gav)
                            throws Exception

Retrieve an artifact that was part of the original build using a full or simplified Maven GAV specifier.

The following formats of GAVs are supported:

• groupId:artifactId
• groupId:artifactId:version
• groupId:artifactId:packaging:version
• groupId:artifactId:packaging:version:classifier

Only artifacts that were compiled with the user's project with a scope of compile are available through lookup.

In the variants that include a version parameter, it may be replaced by a literal asterisk in order to avoid hard-coding versions into the application.

Parameters:

gav - The Maven GAV.

Returns:

The located artifact, as a JavaArchive.

Throws:

Exception - If the specified artifact is not locatable.

artifact

public static JavaArchive artifact(String gav,
                                   String asName)
                            throws Exception

Retrieve an artifact that was part of the original build using a full or simplified Maven GAV specifier, returning an archive with a specified name.

Parameters:

gav - The Maven GAV.

Returns:

The located artifact, as a JavaArchive with the specified name.

Throws:

Exception - If the specified artifact is not locatable.

See Also:

artifact(String)

allArtifacts

public static List<JavaArchive> allArtifacts()
                                      throws Exception

Retrieve all dependency artifacts for the user's project.

Returns:

All dependencies, as JavaArchive objects.

Throws:

Exception

configView

public ConfigView configView()

Retrieve the configuration view.

Returns:

The configuration view.

stageConfig

@Deprecated
public StageConfig stageConfig()

Deprecated.

Retrieve the configuration view in a deprecated manner.

Returns:

The ConfigView through a deprecated interface.

See Also:

configView()