Installation

Getting Started

Install JEM the BEE

Here is the list of actions you must do to install JEM node:

1. Check if your environment can fit JEM requirements (OS must in the list of system requirements, Java runtime - or development kit - 6 or higher) must be installed).
2. Download JEM distribution file.
3. Unzip it where you want.
4. Assign to ${jem_home} variable the value of folder you chosen to unzip JEM and add jemhome to that name. Here an example: if you unzip on /opt/jem folder, jem_home=/opt/jem/jemhome.
5. Go inside the config folder
6. Fill create_node.properties file. See more detail in the relative paragraph.
7. Go inside bin folder and execute jem_createNode.cmd or jem_createNode.sh with the following syntax:

for Windows:

jem_create_node.cmd -properties ../config/create_node.properties

for Linux:

jem_create_node.sh -properties ../config/create_node.properties

After the script execution, you'll have a new environment folder and a node definition ready to start.

1. go inside of environment and node folder.
2. if you want to add other nodes to your environment just execute the jem_createNode.cmd or jem_createNode.sh another time and you will see other node folders inside your environment. Or you can install the same environment in a new machine repeating the above steps.
3. go inside bin folder of each node and execute jem.cmd or jem.sh with console parameter and JEM nodes will start and join together to form your environment. Here an example:

for Windows:

jem.cmd console

for Linux:

jem.sh console

Congratulation, you have just created your first JEM environment (cluster).

For JEM web application, inside of enviroment folder you could find the whole web application (in a WAR file), and you can proceed as following:

1. depoly war file on a servlet container.
2. go inside of war installed path, going to WEB-INF/config.
3. configure if necessary the Apache Shiro configuration file, called jem-node-shiro.ini.
4. start web application. For example if you run the web application inside Tomcat, just put the war file inside apache-tomcat\webapps and start Tomcat then open a browser and go to URL http://localhost:8080/jem_gwt/JEM_gwt.html
5. If you don't have changed Shiro configuration * for the first time type in grantor in the User ID field and any string in Password field

• configure the root user using the Roles tab, clicking search button, clicking on administrator and adding root to the Users fields. Than log out

• access with User ID root and any string in Password field and you will enter the Web Application to handle your environment

create_node.properties

The create_node.properties as you can imagine, is the file that contains all the necessary properties to set up a new environment/node. Below you find the create_node.properties that comes with the JEM distribution. Each property is well commented to explain first of all if it is mandatory or optional and than to explain its purpose. In this paragraph we will explain in detail the mandatory properties and the one advised by JEM the BEE so that you can proceed with a default installation. Note that create_node.propertis comes with most of these properties pre-configured so to make it easier.

• Mandatory properties
  • jem.environment.name, is used for creating the environment folder if does not exist and for configuring the hazelcast cluster and the jem node
  • jem.environment.password, is the password needed to connect to the cluster.
  • Properties relative to the JEM GFS (Global File System)
    • jem.output the path where the stored all output files of job execution. Note that it must exist in the file system and should be mount in a shared file system accessible from all JEM nodes. In Ant JCL can be referenced as ${jem.output}
    • jem.data the path where the datasets and files should be stored. Note that it must exist in the file system and should be mount in a shared file system accessible from all JEM nodes. In Ant JCL can be referenced as ${jem.data}
    • jem.source the path where all the sources file should be placed. Note that it must exist in the file system and should be mount in a shared file system accessible from all JEM nodes. In Ant JCL can be referenced as ${jem.source}
    • jem.binary the path where all the executable files, like .exe, .cmd, .sh ..., that are called at runtime should be stored. Note that it must exist in the file system and should be mount in a shared file system accessible from all JEM nodes. In Ant JCL can be referenced as ${jem.binary}
    • jem.classpath the path where all the library (jars, zip, etc...) relative to an execution of a JCL should be stored. Note that it must exist in the file system and should be mount in a shared file system accessible from all JEM nodes. In Ant JCL can be referenced as ${jem.classpath}
    • jem.library the path where all the native system libraries (like .dll, .so), that are needed by the executable files present in the binary path, should be stored. Note that it must exist in the file system and should be mount in a shared file system accessible from all JEM nodes. In Ant JCL can be referenced as ${jem.library}
    • jem.persistence the persistence path where the database files for the persistence of the jem clustered maps should be stored. Note that it must exist in the file system and should be mount in a shared file system accessible from all JEM nodes
  • Persistence properties. JEM cannot work without configuring a database where to persist JEM Queues
    • jem.db.driver the jdbc driver relative to the database where persistence is configured. Example for mysql: com.mysql.jdbc.Driver
    • jem.db.url the db url for this cluster. Note that each cluster must have different url. Example for mysql: jdbc:mysql://127.0.0.1/JEM
    • jem.db.user the user of the db
    • jem.db.password the password for the db
  • Keystores info
    • jem.keystore.name Is the prefix of the name of the keystore file containing the symmetric key for login phase purpose. The complete name will be [jem.keystore.name][jem.environemnt.name].keystore. The file will be placed in the persistence path
    • jem.keystore.pwd is the password for the keystores. The environment keystore and the user certificates keystores both used when switching on the security module. See security for more detail.
    • jem.crypt.key.pwd is the password to access the symmetric encryption key inside the environment keystore
• Advised security properties
  • jem.login.protocol.enable set it to true permit to accept only nodes that share a common symmetric key and clients launched by user with a known X509 certificate

#----------------------------------------------
# Node configuration properties
#----------------------------------------------
# mandatory, is used for creating the environment folder if does not exist
# and for configuring the hazelcast cluster and the jem node
jem.environment.name=TEST-Env

# mandatory, is the password used to connect to the environment
jem.environment.password=jem_password

# optional default node000 autoincrement, is used for creating the node folder
#jem.node.name=

# optional default ***, is the domain of the node
#jem.domain=

# optional default ***, is the affinity of the node, can be comma separated e.g. classA,Stock
#jem.affinity=

# mandatory, the path where the stored all output files of job execution.
# note that it must exist in the file system and should be mount in a shared file system accessible from all jem nodes
# In Ant JCL can be referenced as ${jem.output}
jem.output=C:/JEM/jem_share/output

# mandatory, the path where the datasets and files should be stored. 
# note that it must exist in the file system and should be mount in a shared file system accessible from all jem nodes
# In Ant JCL can be referenced as ${jem.data}
jem.data=C:/JEM/jem_share/data

# mandatory, the source the path where should be stores all the files 
# that can be considered sources and that can be called at runtime
# note that it must exist in the file system and should be mount in a shared file system accessible from all jem nodes
# In Ant JCL can be referenced as ${jem.source}
jem.source=C:/JEM/jem_share/source

# mandatory, the binary path where all the executable files, like .exe files, 
# that are called at runtime should be stored.
# note that it must exist in the file system and should be mount in a shared file system accessible from all jem nodes
# In Ant JCL can be referenced as ${jem.binary}
jem.binary=C:/JEM/jem_share/binary

# mandatory, the classpath path where all the library (jars, zip, etc...) 
# relative to an execution of a JCL should be stored
# note that it must exist in the file system and should be mount in a shared file system accessible from all jem nodes
# In Ant JCL can be referenced as ${jem.classpath}
jem.classpath=C:/JEM/jem_share/classpath

# mandatory, the library path where all the native system libraries (like .dll, .so), 
# that are needed by the executable files present in the binary path, should be stored
# note that it must exist in the file system and should be mount in a shared file system accessible from all jem nodes
# In Ant JCL can be referenced as ${jem.library}
jem.library=C:/JEM/jem_share/library

# mandatory, the persistence path where the database files for the persistence of the jem clustered maps should be stored.
# note that it must exist in the file system and should be mount in a shared file system accessible from all jem nodes.
jem.persistence=C:/JEM/jem_share/persistence

#------------------------------------------------------
# Properties for the persistence of the jem map. Use
# this property to define the database for the relative
# environment
#-------------------------------------------------------
# mandatory, there is not default.
jem.db.driver=com.mysql.jdbc.Driver

# mandatory, there is not default. Note that if you have multiple cluster
# you have to specify different url for each cluster.
jem.db.url=jdbc:mysql://127.0.0.1/JEM

# mandatory, default is root
jem.db.user=

# mandatory, there is not default.
jem.db.password=

#------------------------------------------------------
# Node login security module properties
#
# this section can enable a login process protected
# by a symmetric key. For more detail see documentation 
#-------------------------------------------------------
# optional, valid value are true or false, default is false
# if set to true and no one of the other properties are set, by default the environment will create and use
# a symmetric key store in the file: jem.persistence/jemencryption_[jem.environment.name].key
jem.login.protocol.enable=true

# is the prefix of the name of the file for the keystore containing the symmetric 
# key for encryption. The complete name will be [prefix]_[jem.environment.name].keystore
# the file will be placed in the persistence path (see property jem.persistence)
jem.keystore.name=

# mandatory, is the password of the keystore
jem.keystore.pwd=jem_password

# mandatory, is the password of the symmetric key used for encryption and decryption 
jem.crypt.key.pwd=jem_password

#-------------------------------------------
# Hazelcast cluster configuration properties
#-------------------------------------------
# optional default 233.0.0.1, is the multicast-group on hazelcast
#jem.multicast.group=

# optional default 54327, is the multicast-port on hazelcast
#jem.multicast.port=

# optional default 5710, is the aouto-increment port in hazelcast
#jem.port.autoincrement=	

# optional default will not enable the hazelcast interface, otherwise hazelcast 
# interface will be enabled with the setted value  
#jem.interface=

Hello Word

Now that you have set up your cluster and the web application to handle the cluster, it's time for the Hello word ! JEM the BEE it's a Job Entry Manager for a Batch Execution Environment so guess what we are going to do ? Submitting a job that say Hello World and monitoring the execution inside the web application. To submit a job inside JEM the BEE we first have to define a JCL. JEM the BEE actually have 2 JCL type, Ant and Spring Batch. In this example we will make use of Ant type.

• Create the JCL and save it in a file. For example: C:/tmp/HelloWorld.xml

<?xml version="1.0"?>
<project name="HELLO_WORLD" default="HelloWord" basedir=".">
   <description>
      Hello World 
   </description>
   <property name="jem.job.name" value="HELLO_WORLD"/>
   <property name="jem.job.environment" value="TEST-Env"/>
   <target name="HelloWord">
      <echo> User:${user.name} </echo>
      <echo> Hello World </echo>
   </target>
</project>

• Submit the JCL. Before doing this be shure to have at least a runnig node for the environment TEST-Env. To submit a job, JEM the BEE give to user 3 different option throgh 3 different command that you will find inside jem_home/bin
  • jem_localhost_submit.cmd. Doesn't need the web application to be running but must be execute inside local host. To run it use the following shell command from the jem_home/bin directory: For Windows:

jem_localhost_submit.cmd -password jem_password -env TEST-Env -port 5710 -jcl file:/C:/tmp/HelloWorld.xml -type ant

For Linux:

jem_localhost_submit.sh -password jem_password -env TEST-Env -port 5710 -jcl file:/C:/tmp/HelloWorld.xml -type ant

* jem\_submit.sh. Need the web application to be running. To run it use the following shell command from the jem\_home/bin directory

For Windows:

jem_submit.cmd -password jem_password -jcl file:/C:/tmp/HelloWorld.xml -type ant -host http://localhost:8080/jem_gwt

For Linux:

jem_submit.sh -password jem_password -jcl file:/C:/tmp/HelloWorld.xml -type ant -host http://localhost:8080/jem_gwt

* jem\_http\_submit.cmd. Need web application to be running. To run it use the following shell command from the jem\_home/bin directory

For Windows:

jem_http_submit.cmd -jcl file:/C:/tmp/HelloWorld.xml -type ant -host http://localhost:8080/jem_gwt -user root -password xxxx

For Linux:

jem_http_submit.sh -jcl file:/C:/tmp/HelloWorld.xml -type ant -host http://localhost:8080/jem_gwt -user root -password xxxx

For more details about submit command, read the script paragraph.

Once you have succesfully submitted the job, you can monitoring it via web application. More specific you can see if it is in the Input Queue, Running Queue, Routing Queue or Output Queue. If you did everything right, you should see it in the Output queue. This is because the crossing between Input and Running Queue is too fast in this case to see it. So open the web application click the Output tab and the button search

click on the HELLO_WORLD and you should see sominthing like this

click on the JCL tab to see the JCL submitted. Obviously it will be exactly the HelloWorld.xml

click on the Output tab to see the output: JEM log for standard JEM output and JOB log for specific job output

Congratulation, that's it, you just learn out to handle a job via JEM the BEE. Just remember that with Ant JCL and Spring JCL you can run any kind of job either a java program, an executable program, a cmd/sh and much more. For java program you can even configure from web application resources like data sources, jms, ftp and call it from java program. You can easily integrate the submission process with the open source Quartz scheduler. JEM the BEE is PaaS (platform as a service) for batch execution and monitoring.

Advanced Linux Installation

See advanced linux installation

The Jem Home Folders

Now that we have learned the bases about how to handle and monitoring a job with the Hello World example, let go a little deeper inside the structure of the jemhome and see how files and directory are organized.

JEM installation directory (which we will later refer to as ${jem_home}) is organized in this way:

bin folder

The bin folder contains the following files:

• jem_console.cmd: is a console for jem command
• jem_console.sh: same as jem_console.cmd but for linux
• jem_create_node.cmd: is the command to use to create a node/environment. Accept the following arguments:
  • -properties indicates the path to the create_node.properties. For more information about this file read specific paragraph
• jem_create_node.sh: same as jem_create_node.cmd but for Linux
• jem_http_submit.cmd: command used to submit a job via http, it needs the web application to be running. See Submitting job
• jem_http_submit.sh: same as jem_http_submit.cmd but for Linux
• jem_localhost_submit.cmd: command used to submit a job, it doen't need the web application to be running but it must be launched inside the host that contains the JEM environment. See Submitting job
• jem_localhost_submit.sh: same as jem_localhost_submit.cmd but for Linux
• jem_submit.cmd: command to submit a job connecting to the cluster, it needs the web application to be running. See Submitting job
• jem_submit.sh: same as jem_submit.cmd but for Linux

config folder

The config folder contains the following files:

• common.conf contains common configuration for all script do not modify it
• create_node.properties for more detail see specific paragraph

lib folder

The lib folder contains all the libraries used by JEM. The complete list of the libraries and their licenses is here.

Furthemore you can find the JEM libraries in the same folder:

• jem.jar
• jem-enterprise.jar. To activate enterprise feature you will need valid license

src folder

The src folder contains all necessary files to create a new environment/node we will not going to explore this folder

The environment folder

After installation, you should run the jem_create_node script, in order to create a new environment. Among other configuration, it will create a new folder, with the same name as the environment, with the following structure (in this example, the environment name is TEST-Env):

All the needed configuration files are created based on the create_nodes.properties file. So, once created, a node should be ready to start.

The TEST-Env/config folder contains the following:

• env_common.conf common configuration for all nodes that belong to this environment

The TEST-Env/node-000/bin folder contains the following:

• jem.cmd used to start the node from windows OS. It accepts the following arguments:
  • console to start the node from console
  • install to install the node as a windows service
  • start to start the service
  • stop to stop the service
  • pause to pause the service
  • resume to resume the service
  • status to know the status of the service
  • remove to remove the service
  • restart to restart the service
• jem.sh used to start the node from linux OS. It accepts the following arguments:
  • console to start the node from console
  • install to install the node as a daemon
  • start to start the daemon
  • stop to stop the daemon
  • pause to pause the daemon
  • resume to resume the daemon
  • status to know the status of the daemon
  • remove to remove the daemon
  • restart to restart the daemon
• other files present in this folder are used by the above command to start properly

The TEST-Env/node-000/config folder contains the following:

• jem-node.xml is JEM configuration file relative to the node (we will later see the common part that will be inside the GFS). For any detail about node configuration see Congifuring JEM node.
• node_wrapper.conf is the part of configuration needed to start the node as a service/deamon (Tanuki Java Service Wrapper).

The TEST-Env/node-000/logs folder contains the following:

• jem.log is the log of this node
• wrapper.log is the log for this node if started as a service/deamon

GFS Folders

The jem_create_node command as we have already seen, update the ${jem.home} folder adding new folder relative to environment and nodes. It also update the persistence folder of the GFS (global file system) adding the following subfolders:

• TEST-Env is the folder relative to the environment created
  • config
    • emailTemplate.xml
    • jem-env.xml
    • jem-env-hazelcast.xml
    • log4j.xml
  • keystore
    • **TEST-Env.keystore *** TEST-Env.keystore.backup
    • **user_certificates_TEST-Env.keystore *** user_certificates_TEST-Env.keystore.backup
  • policy
    • **policy.js *** policy.groovy
  • web
    • jem_gwt.war (the war relative to the web application used to manage the TEST-env environment.)

For any detail about cluster configuration files see Cluster configuration. For any detail about keystores see Security. For any detail about global file system seeGFS

Access Maint

For debug or maintainance purposes it's possible to start JEM node in access maint, setting a boolean system property, as following:

java org.pepstock.jem.node.Main ... -Djem.access.maint=true ....

In access maint, JEM doesn't work with jobs queues and stops all activities about statistics management.

Automatically JEM node is set to DRAINED and it's not possible to start it.

When debug or maintance is ended, restart node without the system property.

Check version

JEM group can work with different versions of JEM on nodes but it's suggested to have the same level of version and release inside the group. JEM node checks during the startup if the version od node is the same of others. By default, the check generates a WARNING if there is a disalignment between versions. It's possible to block JEM node startup, setting a boolean system property, as following:

java org.pepstock.jem.node.Main ... -Djem.check.version=true ....

By default, jem.check.version property is set to false.