Deployment tool

TIBCO BusinessEvents® Extreme ships with a deployment tool that is used to deploy applications to TIBCO BusinessEvents® Extreme nodes. The deployment tool can be used from the command line or via a Java IDE. The TIBCO BusinessEvents® Extreme deployment tool is named deploy.jar.

The general syntax for using the deployment tool is:

java [local JVM options] -jar deploy.jar [options] <target> [application parameters]
java [local JVM options] -jar deploy.jar [options] help

deploy.jar must be specified as the first -jar option. This ensures that the deployment tool gets control during the execution of the application and manages execution and debugging of the application on an TIBCO BusinessEvents® Extreme node.

[Warning]

Attempting to execute an application that uses TIBCO BusinessEvents® Extreme classes without specifying the deploy.jar file as the first -jar option will cause a Java stack dump (example below) because the TIBCO BusinessEvents® Extreme classes cannot execute outside of an TIBCO BusinessEvents® Extreme JVM:

Exception in thread "main" java.lang.SecurityException: Prohibited package name: java.lang
at java.lang.ClassLoader.preDefineClass(ClassLoader.java:479)
at java.lang.ClassLoader.defineClass(ClassLoader.java:614)
at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:124)
at java.net.URLClassLoader.defineClass(URLClassLoader.java:260)
at java.net.URLClassLoader.access$100(URLClassLoader.java:56)
at java.net.URLClassLoader$1.run(URLClassLoader.java:195)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:188)
at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
at sun.misc.Launcher.loadClass(Launcher.java:268)
at java.lang.ClassLoader.loadClass(ClassLoader.java:251)
at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:319)
at pojopersistent.Main.main(Main.java:23)

[local JVM options] is used to pass options to the local JVM. These options are specific to the version of the local JVM.

[options] consists of any combination of JVM options (See the section called “Supported JVM properties”) or deployment tool options (See Table 14.1, “Deployment tool options”). JVM options are prefixed with a "-", while deployment tool options are of the form name = value.

<target> is the application archive file, e.g. a JAR file, or class that will be executed on the node.

[application parameters] are application specific parameters that are passed to the application program's main.

The help command displays the usage message.

Table 14.1, “Deployment tool options” summarizes the supported deployment tool options:

Table 14.1. Deployment tool options

OptionDescription
adminportThe administration port of the node that should be used to run the application.
buildtypeThis option specifies the type of binaries used by the JVM. The valid values are PRODUCTION or DEVELOPMENT. If not specified, the JVM will use the same binary type as the node it runs in.
copytargetA boolean flag which controls whether or not to copy the <target> parameter to the node when detach=true. If copytarget=false, <target> must exist in a deployment directory on the server. It is an error to set copytarget=true when detach=false or <target> is not an archive file, e.g. a JAR file. (default: false).
debugAn enumeration indicating the level of diagnostic output. The valid values are enable - a high level description of the deployment tool activity, verbose - detailed description of deployment tool activity, or disable - no diagnostic output. (default: disable).
detachA boolean flag controlling the deployment mode. A value of false causes the deployment tool to operate in attached mode. A value of true causes the deployment tool to operate in detached mode. (default : false).
detachtimeoutThe number of seconds to wait before exiting, when deploying in detached mode (detach = true). The state of the deployed application is validated for the specified timeout value before exiting (default: 10).
discoverytimeoutThe number of seconds to wait while resolving a servicename (default: 10).
displayversionA boolean flag indicating whether the product version information should be displayed (default: true).
domainnameThe name of the domain that the application is to run on. When this option is used, the deployment tool must connect to a Domain Manager node which is managing the given domain. The application will execute on all nodes in the domain.
domaingroupThe name of the domain group that the application is to run on. When this option is used, the deployment tool must connect to a Domain Manager node which is managing the given domain group. The application will execute on all nodes in the domain group.
domainnodeThe name of the domain node that the application is to run on. When this option is used, the deployment tool must connect to a Domain Manager node which is managing the given domain node. The application will execute on the specified node.
exitonfailureControl multi-node completion behavior. A value of true causes the deployment tool to return to the caller when any node returns a non-zero exit code. A value of false causes the deployment tool to not return until all nodes exit. (default: false).
hostnameThe host name running the node that should be used to run the application (default: localhost).
ignoreoptionsfileA boolean flag which can inhibit the default reading of the deploy tool options file (default: false).
jvmnameThe administrative name to assign to the JVM which hosts the application being deployed. Deployment of the application fails if a JVM already exists with this name (default: a generated unique name).

This name will also be used to search for JVM-specific deployment directories when the JVM starts. See TIBCO BusinessEvents® Extreme Administration for information on JVM-specific deployment directories.

keepalivesecondsThe number of seconds that the node should wait before terminating a deployed application when connectivity between the node and the deploy tool is lost (default: 10 seconds).
mirrorclientA boolean option, when given a value of true, insures that the working directory and class paths used by the node match the client. Note this option will only work if the client and node are run on the same machine, or reference identical file systems (default: false).
nodecleanupA boolean flag that controls whether server artifacts (e.g. loaded class files) to start a JVM are removed when the JVM exits. A value of true removes all generated artifacts, a value of false does not. (default: true).
passwordThe password to use when authenticating username during the connection to the node.
remotedebugIf true, require the JVM hosting the application to enable remote debugging (default: false).
remotedebugportThe debugger agent port, to be used by the JVM to listen for remote debugger clients (default: randomly chosen by the JVM).
resetThis option, when given a value of true, requests that all Java objects and any changed type definitions on the node be deleted before the application begins execution. If there is a JVM already running an error will be reported and the new JVM will fail to start. (default: false).
schedulerpolicy The Scheduling policy and priority for the JVM process. The syntax is policy: priority. The valid values for the policy are SCHED_FIFO, SCHED_RR, and SCHED_OTHER. The valid range for priority depends on the policy; for Linux the valid values for SCHED_FIFO and SCHED_RR are 1 - 99. See the man page page for sched_setscheduler(2) for more information.

If the schedulerPolicy cannot be set, the JVM process will not be started. In order to use "real-time" policies, the caller needs the approriate permissions. On Linux, a security configuration file can be created to allow users to enable "real-time" policies. As an example, the following:

cat > /etc/security/limits.d/tibco.conf <<EOF
nightly hard rtprio 70
nightly soft rtprio 0
EOF

will allow the user "nightly" to enable either SCHED_FIFO or SCHED_RR with a priority range from 0 to 70.

If running as root, you can set the required permission for root, with the following command:

ulimit -r 99

Run this immediately before starting the node, in the same shell that starts the node.

serverdebugControl server diagnostics. An enumeration value that has one of the following values: enable or disable. A value of enable causes additional server debug tracing. A value of disable disables server debug tracing. (default: disable).
serverdebugfilterInternal. Control server diagnostics. A hexadecimal value, starting with 0x.
serverdebugpauseInternal. Pause process before JVM is launched. Boolean.
servicenameThe service name of the node that is to be used to run the application. This option may be used instead of adminport and hostname.
shutdowntimeoutsecondsThe maximum number of seconds to wait for a JVM to shutdown (default: 60).
suspendIf true, require the JVM to suspend execution before main() is called during remote debugging. This option only applies if remotedebug=true is specified (default: false).
usernameThe user name to use when connecting to a node. The specified value must identify a principal with administrative privileges on the node. Defaults to the user.name system property, which is set to be the UID of the user who executed the deployment tool client JVM.

Reset

The reset option provides development support for changing the shape of Managed Objects in shared memory. It has no affect on non-managed Java objects.

[Warning]

The reset option should only be used during development. It should never be used on a production system.

Reset processing takes place during JVM initialization. The following steps are taken to reset shared memory:

  1. Check to make sure that there are no other JVMs running. If there are other JVMs running, the new JVM initialization will fail with an error message. Reset can only be done when there are no JVMs running on a node.

  2. Delete all managed objects in shared memory. If the managed object is a distributed object on a remote node, dispatch the delete to the remote node. If the remote node cannot be reached, delete the cached copy on the local node.

  3. Remove all type definitions from shared memory. They will be redefined as part of class loading as the application executes.

Examples of changing the shape of a Managed Object are:

  • adding a field to a class

  • removing a field from a class

  • changing the type of a field in a class

  • changing the inheritance hierarchy

TIBCO BusinessEvents® Extreme detects when the shape of a Managed Object changes and fails the load of the changed class definition if reset = false.

For example, if Example 14.1, “Type change” is run twice - once with m_string not commented out, and then again with m_string commented out with reset = false (the default value):

Example 14.1. Type change

//     $Revision: 1.1.2.1 $

package com.kabira.snippets.reference;

import com.kabira.platform.Transaction;
import com.kabira.platform.annotation.Managed;

/**
 * Snippet used to demonstrate changing the shape of a class
 * <p>
 * <h2> Target Nodes</h2>
 * <ul>
 * <li> <b>domainnode</b> = A
 * </ul>
 */
public class Shape
{
    /**
     * A managed object
     */
    @Managed
    public static class ShapeChange
    {
        private    int    m_int;
        //
        //    Uncomment this field after running once to see
        //    type conflict
        //
        // private String    m_string;    
    }
    
    /**
     * Main entry point
     * @param args  Not used
     */
    public static void main(String args[])
    {
        new Transaction("Create Object")
        {
            @Override
            protected void run() throws Rollback
            {
                new ShapeChange();
            }
        }.execute();
    }
}

On the second run, the following exception is thrown:

Example 14.2. Type change - second run output

[A] Java main class 
                    com.kabira.snippets.reference.Shape.main exited with an exception.
[A] Java exception occurred: Audit of class
                    [com.kabira.snippets.reference.ShapeChange] failed:
                    Type did not match. New type name 
                    com.kabira.snippets.reference.ShapeChange - existing type
                    name com.kabira.snippets.reference.ShapeChange.
                    Changed values :numberSlots:objectSize:;
                    the class will not be loaded.
[A] at com.kabira.platform.classloader.ClassLoader.createKTPTypeDescriptor
                   (Native Method)
[A] at com.kabira.platform.classloader.ClassLoader.defineManagedClass
                   (ClassLoader.java:642)
[A] at com.kabira.platform.classloader.ClassLoader.findClass(ClassLoader.java:302)
[A] at com.kabira.platform.classloader.ClassLoader.loadClass(ClassLoader.java:228)
[A] at java.lang.ClassLoader.loadClass(ClassLoader.java:251)
[A] at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:319)
[A] at com.kabira.snippets.reference.Shape.run(Shape.java:37)
[A] at com.kabira.platform.Transaction.execute(Transaction.java:132)
[A] at com.kabira.snippets.reference.Shape.main(Shape.java:31)
INFO: Application [com.kabira.snippets.reference.Shape6] running on node [A]
                   exited with status [-1]
INFO: Run of distributed application [com.kabira.snippets.reference.Shape6] complete.

Setting reset = true will avoid this exception.

Highly available and distributed systems

When highly available or distributed Managed Objects are used in an application, the type definition for these classes are pushed to all nodes in a cluster. To ensure that the type definitions stay consistent on all nodes, the same value for the reset option must be sent to all nodes. This is accomplished using the Distributed Development features as described in Chapter 2, Developing distributed applications.

Using inconsistent values for the reset option on nodes in a cluster will cause application failures because of the inconsistent type definitions on the nodes. The cluster must be restarted to resolve this problem.

Security

The TIBCO BusinessEvents® Extreme deployment tool will prompt for a password if one is not specified on the command line, or in the options file, using the password parameter.

The TIBCO BusinessEvents® Extreme deployment tool always uses SSL connections to TIBCO BusinessEvents® Extreme nodes. This requires an SSL TrustManagerFactory algorithm that supports storage and management of X.509v3 credentials. By default the SunX509 TrustManagerFactory is used. If that TrustManagerFactory algorithm is not supported in the JRE being used to execute the deployment tool, an alternative algorithm can be specified using the ssl.TrustManagerFactory.algorithm JVM system property.

The algorithm specified using the above property must reference a TrustManagerFactory which supports storage and management of X.509v3 credentials and is provided by the JRE being used.

Options file

When the TIBCO BusinessEvents® Extreme deployment tool is executed it looks for the following file:

<user home directory>/.ast/options    

If this file exists, any deployment tool command line options in the options file are used. Command line options specified in the options file have the same affect as the same command line option specified on the command line.

Options on the command line override the same option in the options file. For example if the command line contains -jar deploy.jar debug=true and the options file contains debug = false, a debug value of true is used for the application execution.

The options file must follow the format below.

#
#     Any line starting with '#' is ignored
#
#     Each option is specified on a separate line, as follows:
#
<option name> = <option value>[newline]

For example, the following options file would set up the default username and password for use with the TIBCO BusinessEvents® Extreme development nodes:

#
#       Username and password for TIBCO BusinessEvents® Extreme
 development nodes
#
username = guest
password = guest

Default JVM properties

The options file also supports defining default JVM properties for the TIBCO BusinessEvents® Extreme JVM. Default TIBCO BusinessEvents® Extreme JVM properties are specified using the jvmoptions option name. Here is an example of using the jvmoptions option.

#
#       Username and password for TIBCO BusinessEvents® Extreme
 development nodes
#
username = guest
password = guest

#
#       Default JVM options
#
jvmoptions = -Duser.name=fred -Duser.country=US

Deployment example

Example 14.3, “Deployment example” shows how to deploy a simple Java program to an TIBCO BusinessEvents® Extreme node from the command line.

Example 14.3. Deployment example

//     $Revision: 1.1.2.1 $

package com.kabira.snippets.reference;

/**
 * Simple hello world snippet
 * <p>
 * <h2> Target Nodes</h2>
 * <ul>
 * <li> <b>domainnode</b> = A
 * </ul>
 */
public class HelloWorld
{
    /**
     * Main entry point
     * @param args  Not used
     */
    public static void main(String args[])
    {
        System.out.println("Hello World");
    }
}


#
#    NOTE: Remove the package statement from the HelloWorld.java snippet above
#    to work with the example steps below.
#

#
#    Compile the program using the native javac on the host machine
#
javac HelloWorld.java

#
#    Excute the program against an TIBCO BusinessEvents® Extreme
 node - assumes deploy.jar is in local directory
*
java -jar deploy.jar hostname=192.168.1.128 adminport=2001 \
     username=guest password=guest HelloWorld

#
#    The output from the command
#
INFO: deploy.jar version: [core_linux081117]
INFO: node version: [core_linux081117]
Hello World