Creating a Domain

This chapter describes the requirements for creating a domain, how to create a domain using a tool provided by JEUS (jeusadmin), and the directory structure of a domain.

1. Creating a Domain

A domain directory is created when a domain is created. Scripts and basic configuration files that start and stop servers in the domain are created in this directory. The parent directory for each domain is DOMAIN_HOME and its path is as follows:

JEUS_HOME/domains/<domain_name>

When a domain is created, it only contains Master. Managed serves can be added using jeusadmin. After an MS is added and started, it receives the domain information from Master. In other words, Master creates the domain directory when the domain is created, and managed servers create the domain directory through Master when they start.

A domain can be created using Ant task or jeusadmin. The following are the requirements.

  • Network configuration

    JEUS requires an IP address and port number because it shares domain server status using multicast. If servers exist outside of the local network and are not able to share information via multicast, TCP is used instead. This is called virtual multicasting in JEUS, and it can be configured when a domain is created.

    Since server information is shared using the default listener IP address and port number on the server, all servers in the domain that exist outside of the local network must specify a listener IP address and port number. They must also set the option to disable multicasting.

  • Default Master configuration

    Each domain must contain a Master. A default configuration is used and can be further configured by the user. Dynamic configuration items can be changed at any time, but static items must be configured when the domain is created. Examples of static configuration items include the default listener IP address, port number, and JVM configuration.

1.1. Creating a Default Domain

This section describes how to create the default domain. When the default domain is created, Virtual Multicast is disabled.

The following are the command attributes for Ant task and jeusadmin.

Attribute Default Value

Master name

adminServer

Listen IP address

0.0.0.0 / 0:0:0:0:0:0:0:0

Listen port number

9736

user name

administrator

Multicast IP address

230.30.1.1 / FF01:0:0:0:0:0:0:1

Multicast port number

3030

  • Creating a domain with Ant

    The default configuration values when using Ant are defined in JEUS_HOME/setup/domain-config-template.properties. The following is an example of configuring the attributes. The default value is used if an attribute is not configured.

    JEUS_HOME/setup$ ant create-domain -Ddomain=jeus_domain
-Dservername=adminServer
-Djeus.address=0.0.0.0
-Djeus.port=9736
-Dtransport.address=230.30.1.1
-Dtransport.port=3030

  • Creating a domain with jeusadmin

    The default configuration values when using jeusadmin are defined in JEUS_HOME/setup/domain-config-template.properties. If jeus.password is set in domain-config-template.properties, use the configured value. Otherwise, enter the password as in the following example.

    offline>create-domain -domain jeus_domain -mastername adminServer -taddress 230.30.1.1 -tport 3030
Enter the password for [administrator]: **********
Confirm the password: **********
Do you want to encrypt the password? (y/n): y
================================================================================
The domain [jeus_domain] was created successfully.
+-------------------------------+----------------------------------------------+
|         Property              |                        Value                 |
+-------------------------------+----------------------------------------------+
| Domain name                   | jeus_domain                                  |
| Master Name                   | adminServer                                  |
| Master Base Listen Port       | 9736                                         |
| Master Base Listen Address    | 0.0.0.0                                      |
| HTTP Port                     | 8088                                         |
| User Name                     | administrator                                |
| Node Name                     | node1                                        |
| Password                      | {base}amV1cw==                               |
| JVM Option                    | -Xmx256m -XX:MaxMetaspaceSize=128m           |
| Production Mode               | true                                         |
| Transport Type                | HYBRID                                       |
+-------------------------------+----------------------------------------------+
===============================================================================

1.2. Creating a Domain that Uses Virtual Multicast

This section describes how to check if the environment supports the IP Multicast functionality, and how to create a domain that uses the virtual multicasting when the environment does not support the IP multitasking or the domain goes beyond the subnet range.

To check if the environment supports IP multitasking, execute the two mcastSender and mcastReceiver test scripts. The two scripts are in JEUS_HOME/bin. Execute each one on a different machine as in the following.

JEUS_HOME/bin$ mcastReceiver -addr 224.0.0.1 -port 3030
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:2a37:37ff:fe1e:fc4%5
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /192.168.0.26
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:3e07:54ff:fe6f:95e%4
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /61.77.153.207
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:0:0:0:1%1
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /0:0:0:0:0:0:0:1
Socket == 0.0.0.0/0.0.0.0 : 3030, bound to /127.0.0.1
JEUS_HOME/bin$ mcastSender -addr 224.0.0.1 -port 3030
1 == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:2a37:37ff:fe1e:fc4%5
2 == 0.0.0.0/0.0.0.0 : 3030, bound to /192.168.0.26
3 == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:3e07:54ff:fe6f:95e%4
4 == 0.0.0.0/0.0.0.0 : 3030, bound to /61.77.153.207
5 == 0.0.0.0/0.0.0.0 : 3030, bound to /fe80:0:0:0:0:0:0:1%1
6 == 0.0.0.0/0.0.0.0 : 3030, bound to /0:0:0:0:0:0:0:1
7 == 0.0.0.0/0.0.0.0 : 3030, bound to /127.0.0.1

This test attempts to send and receive IP multicast packets through all network interfaces. The addresses at the top are for all network interfaces.

At the prompt that appears on the Sender side, enter a message that is sent to the Receiver. If the Receiver cannot receive the message, it means that IP multicasting is not working properly. In such a case, set the following virtual multicast configuration. The following is the execution of a test message for the mcastSender example above.

> test
>
test [sender = 192.168.0.26 : 5555], [bind_addr=/127.0.0.1]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:3e07:54ff:fe6f:95e%4]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/61.77.153.207]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/192.168.0.26]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]
test [sender = 192.168.0.26 : 5555], [bind_addr=/fe80:0:0:0:2a37:37ff:fe1e:fc4%5]

Since the same message is sent/received through all network interfaces of the machine, duplicate messages can be transmitted. To quit the test, enter 'quit' or 'exit' at the Sender’s prompt. At the Receiver’s end, press <Ctrl> + C to quit.

To see help, enter '-help' as a parameter or do not include a parameter.

The following describes how to configure a virtual multicast domain. The default attribute values are the same as those in Creating a Default Domain. The virtual multicast has two types: MESH and Tree.

  • Creating a domain with Ant (MESH type)

    JEUS_HOME/setup$ ant create-domain
                    -Ddomain=jeus_domain
                    -Djeus.address=192.168.34.1
                    -Dtransport.type=MESH

  • Creating a domain with jeusadmin (MESH type)

    offline>create-domain -domain jeus_domain -baseaddress 192.168.34.1 -ttype MESH
Enter the password for [administrator]: **********
Confirm the password: **********
Do you want to encrypt the password? (y/n): y
================================================================================
The domain [jeus_domain] was created successfully.
+-------------------------------+----------------------------------------------+
|         Property              |                        Value                 |
+-------------------------------+----------------------------------------------+
| Domain name                   | jeus_domain                                  |
| Master Name                   | adminServer                                  |
| Master Base Listen Port       | 9736                                         |
| Master Base Listen Address    | 192.168.34.1                                 |
| HTTP Port                     | 8088                                         |
| User Name                     | administrator                                |
| Node Name                     | node1                                        |
| Password                      | {base}amV1cw==                               |
| JVM Option                    | -Xmx256m -XX:MaxMetaspaceSize=128m           |
| Production Mode               | true                                         |
| Transport Type                | MESH                                         |
+-------------------------------+----------------------------------------------+
================================================================================

  • Creating a domain with jeusadmin (TREE type)

    offline>create-domain -domain jeus_domain -baseaddress 192.168.34.1 -ttype TREE -taddress 192.168.34.1 -tport 9736
Enter the password for [administrator]: **********
Confirm the password: **********
Do you want to encrypt the password? (y/n): y
================================================================================
The domain [jeus_domain] was created successfully.
+-------------------------------+----------------------------------------------+
|         Property              |                        Value                 |
+-------------------------------+----------------------------------------------+
| Domain name                   | jeus_domain                                  |
| Master Name                   | adminServer                                  |
| Master Base Listen Port       | 9736                                         |
| Master Base Listen Address    | 192.168.34.1                                 |
| HTTP Port                     | 8088                                         |
| User Name                     | administrator                                |
| Node Name                     | node1                                        |
| Password                      | {base}amV1cw==                               |
| JVM Option                    | -Xmx256m -XX:MaxMetaspaceSize=128m           |
| Production Mode               | true                                         |
| Transport Type                | TREE                                         |
| Transport address             | 192.168.34.1                                 |
| Transport port                | 9736                                         |
+-------------------------------+----------------------------------------------+
================================================================================

2. Configuring a Domain

This section describes how to change the composition of a domain by adding servers and clusters to the domain created in Creating a Domain.

The Master must be started to add servers and clusters which changes the configuration. Refer to Changing Domain Settings for detailed information about changing the configuration.

DOMAIN_HOME/bin$ startMasterServer -u jeus -p jeus

2.1. Using the Console Tool

The following are the steps for adding a server and a cluster.

  1. Adding a node

  2. Adding a managed server (MS)

  3. Adding a cluster

Adding a node

A node refers to JEUS installed on a specific machine. Starting a server via the Master on a node requires configuring information about that node. If your OS is UNIX-based, an SSH node using SSH is supported. You can specify the host address of the machine, the JEUS installation directory, the user name for SSH access, the private key file path for SSH access, and the SSH access port number. One node is created by default when JEUS is installed, and you can use it by changing the settings. For detailed information on node management, refer to JEUS Node Manager Guide.

The following how to add a node using jeusadmin.

The add-java-node command adds a node called 'node1' as follows:

[MASTER]domain1.adminServer>add-java-node node1 -host 192.168.34.65 -port 7730
The node [node1] was successfully added.

The add-ssh-node command adds an SSH type node to JEUS as follows:

[MASTER]domain1.adminServer>add-ssh-node node2 -host 192.168.23.129
-dir /home/jeus/jeus8 -user jeus -privatekey /home/jeus/.ssh/id_rsa
The node [node2] was successfully added.
Adding a managed server (MS)

Managed Server configuration cannot be changed dynamically.

Similar to the default configuration of Master, when the domain described in Creating a Domain is created, default configuration set when adding an MS is not applied dynamically. Choose a unique IP address and port number that do not conflict with other servers, and configure the JVM options. If a domain does not exist on the local network, specify an IP address to use instead of the default value of 0:0:0:0. Since server names in a domain must be unique, verify that there are no conflicts. Since the servers in the example are in the same cluster, settings that exist at the cluster level do not need to be configured separately for each server.

The following are the steps for adding an MS by using jeusadmin.

Add an MS named 'server1', using the add-server command. Add 'server2' in the same way. For detailed instructions about using the add-server command, refer to add-server in JEUS Reference Guide.

[Master]domain1.adminServer>add-server server1 -node node1 -addr 192.168.34.1 -port 9836
Successfully performed the ADD operation for server (server1).
 NOTICE : base-addr [192.168.34.1] base-port [9836] http-port [8088]
Check the results using "list-servers or add-server"
Adding a cluster

When adding a cluster, load balancing, failover, and the servers in the cluster must all be configured. Refer to Cluster Settings for detailed information about configuring a cluster.

The following are the steps for adding a cluster.

  1. Add a cluster 'cluster1' that consists of server1 and server2 using the add-cluster command. Refer to add-cluster in JEUS Reference Guide for detailed instructions about using the add-cluster command.

    [Master]domain1.adminServer> add-cluster cluster1 -servers server1,server2
Successfully performed the ADD operation for cluster (cluster1).
Check the results using "list-clusters or add-cluster"

  2. After adding all items up to the cluster, use the serverinfo command to verify the result.

    [Master]domain1.adminServer>serverinfo
Information about Domain (domain1)
 ===============================================================================================
 +--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
 | Server |  Status | Node|  PID  | Clus|  Latest Start  | Need to | Listen Ports| Running     |
 |        |         |Name |       | ter |Time / Shutdown | Restart |             | Engines     |
 |        |         |     |       |     |     Time       |         |             |             |
 +--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
 | adminSe| RUNNING | N/A | 5360  | N/A | 2016-08-23     | false   | base-192.168| jms,        |
 |rver(*) |(00:01:11|     |       |     |(Tue) PM        |         |.34.3:9736   | ejb, web    |
 |        |)        |     |       |     |03:53:28 KST    |         | http-server-|             |
 |        |         |     |       |     |                |         |0.0.0.0:8088 |             |
 |        |         |     |       |     |                |         |jms-internal-|             |
 |        |         |     |       |     |                |         |0.0.0.0:9741 |             |
 +--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
 | server1| RUNNING |node1| 6424  | clus| 2016-08-23     | false   | base-192.168| jms,        |
 |        |(00:00:03|     |       |ter1 |(Tue) PM        |         |.34.1:9836   | ejb, web    |
 |        |)        |     |       |     |03:54:37 KST    |         |             |             |
 +--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
 | server2| RUNNING |node2| 3012  | clus| 2016-08-23     | false   | base-192.168| jms,        |
 |        |(00:00:03|     |       |ter1 |(Tue) PM        |         |.34.2:9936   | ejb, web    |
 |        |)        |     |       |     |03:54:36 KST    |         |             |             |
 +--------+---------+-----+-------+-----+----------------+---------+-------------+-------------+
 ===============================================================================================

3. Directory Structure

When JEUS is installed, JEUS_HOME directory and jeus_domain, which is the sub directory of JEUS_HOME, are created.

This section describes the directory structure with the assumption that the path of the user home is '/home/user1' and the domain is called 'domain1'.

3.1. JEUS_HOME Directory

The JEUS directory structure is as follows. JEUS_HOME is the top-level directory of JEUS. The actual directory name and location can be configured during the installation.

/home/jeus/JEUS_HOME

The following is the directory structure of JEUS_HOME.

{JEUS_HOME}
   |--bin
   |    |--[01]startMasterServer
   |    |--[01]startManagedServer
   |    |--[01]stopserver
   |    |--[01]jeusadmin
   |--derby
   |--docs
   |--domains
   |    |--domain1
   |    |--[X]nodes.xml
   |--lib
   |--license
   |--nodemanager
   |--setup
   |--templates

* Legend
- [01]: binary or executable file
- [X] : XML document
- [J] : JAR file
- [T] : Text file
- [C] : Class file
- [V] : java source file
- [DD] : deployment descriptor
bin

Contains executable files, including the server’s start and stop scripts and the JEUS console tool (jeusadmin), as well as configuration files.

  • Executable Files

    Executable File Description

    appclient
    appclient-ws

    Runs an application client that can use some of the Jakarta EE services provided by JEUS.

    appcompiler

    Compiles the application’s EJB interface Impl, Skeleton, and Stub classes, and JSP to generate servlet classes, web service endpoint classes, etc.

    configMigration

    Upgrades a domain.xml file from one version to another.

    ejbddinit

    Creates the EJB module DD file (jeus-ejb-dd.xml) using information from ejb-jar.xml and the previously created property file.

    encryption

    Encrypts or decrypts a string.

    jant

    Executes the build.xml file using the ant tool built into JEUS.

    java2wsdl

    Generates WSDL files and JAX-RPC mapping files from Java classes.

    jeusadmin

    Console tool used to directly manage JEUS.

    jeusddupgrade

    Upgrades the JEUS DD files (jeus-ejb-dd.xml, jeus-web-dd.xml, jeus-application-dd.xml) in the previous version of the application to the current version.

    mcastReceiver
    mcastSender

    Used to test whether the environment is capable of using IP Multicast.

    schemagen

    Creates one schema file for each namespace found in the Java classes.

    startCloudServer

    Used when running JEUS in a cloud environment.

    startderby
    stopderby

    Starts or stops the Apache Derby DB required for the Jakarta Batch application.

    startMasterServer
    startManagedServer
    stopServer

    Starts or stops the master or managed server.

    startMasterServerNM

    Starts the master server through the node manager.

    startNodeManager
    stopNodeManager

    Starts or stops the node manager.

    tcpmon

    Monitors TCP packets being sent and received. tcpmon can also inspect HTTP SOAP messages.

    webddgen

    Creates or updates the DD file (jeus-web-dd.xml) of the WEB module.

    wsdl2java

    Generates client-side Java stub source files and server-side web service interface Java source files from a WSDL file.

    wsdl2uddi

    Publishes to UDDI from the WSDL file of a web service.

    wsgen

    Tool for JAX-WS web services that generates WSDL files and JAX-RPC mapping files from Java classes. It can also generate web service policy configuration files.

    wsimport

    Generates client-side Java stub source files and server-side web service interface Java source files from a WSDL file. It can also generate web service policy settings files.

    xjc

    Converts XML schema files into Java language-based JAXB content classes.

  • Configuration Files

    Configuration File Description

    cloudserver.properties

    Defines environment variables applied when running startCloudServer.

    jeus.properties

    Defines environment variables such as JAVA_HOME and JEUS_HOME that are applied when starting the JEUS server.

    logging.properties

    Defines logging properties applied to the Java logger and JEUS logger.
derby

Contains Apache Derby, which allows sample applications and tests to be used easily.

docs

Contains Javadoc documents for the API provided by JEUS.

domains

Contains a DOMAIN_HOME subdirectory for each domain, as well as nodes.xml which includes node information used in JEUS_HOME.

lib

Contains the libraries required to run JEUS. Users do not need to access other directories except the shared directory.

Subdirectory Description

shared

Contains libraries that are used by applications.

To use the libraries, add the information about the libraries to libraries.xml. Also, the reference information of the libraries must be configured in the JEUS Deployment Descriptor (DD) of the application that will reference them.

Refer to Shared Libraries in JEUS Applications & Deployment Guide for detailed information about shared libraries.
license

Contains JEUS license files that are required to run JEUS.

nodemanager

Contains configuration files for using the Java-type node manager. Log files generated by the node manager are also stored in this directory.

setup

Contains the files that are required for implementing JEUS environment.

templates

Contains template files for various configurations and environments.

3.2. Domain Directory

JEUS_HOME/domains/domain1 is the DOMAIN_HOME directory for domain1.

The following is the directory structure of domain1.

domain1
   |--.applications
   |--.deploymentplans
   |--.libraries
   |--bin
   |--config
   |--lib
   |   |--application
   |--servers
.applications

Contains application files managed by the domain. This directory has restricted access. Files can only be added or deleted using the install-application or uninstall-application commands. For details about each command, refer to install-application and uninstall-application in JEUS Reference Guide.

.deploymentplans

Contains deployment plans managed by the domain. This directory has restricted access. Files can only be added or deleted using the install-deployment-plan and uninstall-deployment-plan commands. For details about each command, refer to install-deployment-plan and uninstall-deployment-plan in JEUS Reference Guide.

.libraries

Contains the library files installed in the domain. User access is limited to the directory that JEUS uses. The install-library and uninstall-library can be used to add and delete libraries. For details about each command, refer to install-library and uninstall-library in JEUS Reference Guide.

bin

Contains the Master and MS start and stop scripts.

These have the same function as the startMasterServer, startManagedServer, and stopServer scripts in 'JEUS_HOME/bin' except that they do not need to specify the name of the domain.

config

Contains the backup copies of the domain.xml file. Refer to Changing Domain Settings for detailed information about configuring the domain.

  • security

    Subdirectory Description

    SYSTEM_DOMAIN

    Directory that contains the accounts.xml and policies.xml domain security files. These files contain settings that can be changed dynamically using jeusadmin.

    Refer to Configuring the Security System Domain in JEUS Security Guide for a detailed description of domain security settings.

    security.key

    File that contains the encryption keys that is created when JEUS_HOME/bin/encryption is created. Refer to Configuring Password Security in JEUS Security Guide for a detailed description of the security.key file.

    policy

    Java permissions configuration file. This is unrelated to the JEUS security system; it is used by the Java SE Security Manager.

  • servlet

    Subdirectory Description

    webcommon.xml

    The common configuration file which applies to all web modules on the web engine of a server in the domain.

    For details about this configuration, refer to Directory Structure in JEUS Web Engine Guide.
lib/application

Contains application libraries that are applied to the entire domain.

If there is a duplicate copy of the library in the SERVER_HOME directory, the copy in the SERVER_HOME/lib/application directory has priority, and a warning message is also displayed. For a detailed description of the lib/application directory, refer to lib/application Directory in JEUS Applications & Deployment Guide.

servers

The SERVER_HOME directory is a subdirectory that uses the server name. For a detailed description of the SERVER_HOME directory, refer to Server Directory Structure in JEUS Server Guide.