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

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    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()`

Copyright © 2018 JBoss by Red Hat. All rights reserved.