Search

Java

Version 20.0.7681

Java

The Java edition of includes an embedded Jetty web server so that ArcESB can be run without any external server configuration. In addition, the installation includes a .WAR file that can be deployed to any Java servlet container like Tomcat, Jetty, JBoss, WebLogic, or WebSphere.

The embedded Jetty server requires that JDK 1.8 or later is installed on the machine.

Using the Embedded Jetty Server

To start the embedded Jetty server, simply run the arcesb.jar file located in the Arc installation directory. This directory also contains a service script, which may be used to set up a systemd or init.d service on unix systems.

By default, the embedded server hosts Arc on port 8080 and only accepts plaintext connections (HTTP and not HTTPS).

After starting the server, access the web UI by directing a browser to http://localhost:8080. The default username/password credentials to access the UI are ‘admin/admin’.

Changing the Port

To configure the port that the embedded server listens on, find the ‘arcesb.xml’ file in the installation directory and open it in a text editor. Find the definition of the HTTP connector as indicated by this XML:

<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

Within this definition, modify the following line to change the configured port:

<Set name="port">8080</Set>

Enabling SSL/TLS

Enabling SSL/TLS connections (HTTPS) also involves modifying the ‘arcesb.xml’ file in the installation directory. Find the definition of the HTTP connector:

<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">

Within this definition (as a direct child of the above New element), supply an sslContextFactory argument by adding the following XML block:

<Arg name="sslContextFactory">
  <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
    <Set name="KeyStorePath"><SystemProperty name="arcesb.home" default="." />/keystore</Set>
    <Set name="KeyStorePassword">mypassword</Set>
  </New>
</Arg>

Note: The Arg element shown above must be adjacent to other Arg elements at the beginning of the connector definition. This block must not be placed after the Set element that defines the server port, for example.

The KeyStorePath element defines the location of the SSL/TLS certificate used when hosting the SSL/TLS server. The above example assumes that a ‘keystore’ folder has been created in the Arc installation directory and this folder contains a PFX certificate called ‘mycert’. The KeyStorePassword element should be set to the password that corresponds to the configured certificate.

Change User Credentials

The users that can log into the Arc web UI are defined in the ‘arcesbRealm.properties’ file in the installation directory. Each line in this file defines a user, with the following syntax:

username:password[roles]

Add a new line to define new users, or modify the existing line to change the default login credentials.

Starting and Stopping the Server

If the service script has been used to set up an ArcESB service, please reference the Running as a Service section below. Otherwise, the Running In-Process section is applicable.

Running In-Process

The embedded Jetty server is started by executing the arcesb.jar file extracted from the application download during setup. Standard Java syntax can be used to execute this file and start the server:

java -jar arcesb.jar

To stop the server, simply pass an additional parameter to this command:

java -jar arcesb.jar -stop

Running as a Service

The ArcESB service can be manipulated using standard system service commands, referencing ‘arcesb’ as the name of the service.

To start the service:

systemctl start arcesb

To stop the service:

systemctl stop arcesb

To restart the service:

systemctl restart arcesb

Configuration in Tomcat

Deploy the WAR File

You have several options for deploying a WAR file to Tomcat.

  • Copy the WAR file into the webapps folder.
  • Deploy the WAR file from within the management console in Tomcat. The Tomcat documentation covers this method in more detail.

It is possible that the WAR file may exceed the default maximum size allowed for file uploads in Tomcat. To overcome errors during deployment, you can edit the WEB.XML file of the manager application to allow larger files. Depending on your tomcat configuration, this file may be located in ‘/usr/share/tomcat7-admin/manager/WEB-INF’, or in another similar directory. In this file, you can change the size in bytes of the maximum allowed file size. For example, to allow deployment of a 200MB WAR file, edit the following values to change the maximum allowed file size:

<multipart-config>
	<!-- 200MB max -->
	<max-file-size>209715200</max-file-size>
	<max-request-size>209715200</max-request-size>
	<file-size-threshold>0</file-size-threshold>
</multipart-config>

Allow Tomcat Users to Access Arc

Assign the “arcesb_admin” role to the user you want to be the administrator of the application. If you are using the default user realm for Tomcat, you can add these roles by editing the tomcat-users.xml file located in CATALINA_BASE/conf/tomcat-users.xml. In the following example, the admin user has been given the necessary roles for administrative access to the application:

<user name="admin" password="admin" roles="arcesb_admin,admin-gui,manager-gui,manager-status,manager-script,manager-jmx" />

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart your Tomcat server for the changes to take effect. You can now log in to the application.

Configuration in JBoss

Deploy the WAR File

There are several ways that you can deploy a WAR file to JBoss:

  • You can copy the WAR file into the JBOSS\_HOME/standalone/deployments subfolder.
  • You can also use the JBoss Administration Console to install the WAR file.

Allow Access to JBoss Users

To grant your JBoss user access to the application, assign the user the arcesb_admin role. If you are using the default user realm for JBoss, you can add this role by running the add-user.bat file that comes with the JBoss server.

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

Configuration in WebSphere

Create a Plan to Allow Access to WebSphere Users

To deploy the application WAR file to WebSphere, create a deployment plan. You can use the Plan Creator wizard in WebSphere to create a plan and then deploy the WAR file. You can initialize the wizard from the WebSphere administration console.

Assign the arcesb_admin role to the user or group you will use to log into the application. The following example plan allows access to the system administrator:

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-2.0.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.2">
    <dep:moduleId>
      <dep:groupId>default</dep:groupId>
      <dep:artifactId>arcesb</dep:artifactId>
      <dep:version>1371673558693</dep:version>
      <dep:type>war</dep:type>
    </dep:moduleId>
    <dep:dependencies/>
  </dep:environment>
  <context-root>arcesb</context-root>
  <security-realm-name>geronimo-admin</security-realm-name>
  <app:security xsi:type="sec:securityType" xmlns:sec="http://geronimo.apache.org/xml/ns/security-2.0" xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <sec:role-mappings>
      <sec:role role-name="arcesb_admin">
        <sec:principal name="system" class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"/>
      </sec:role>
      <sec:role role-name="admin"/>
    </sec:role-mappings>
  </app:security>
</web-app>

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

Configure the WebSphere Class Loader

In order for WebSphere to load the application resources correctly, the following steps are required:

  1. Within WebSphere, navigate to: Application -> Application Types -> WebSphere enterprise applications
  2. Select ArcESB
  3. Select ‘Class loading and update detection’
  4. Choose ‘Classes loaded with local class loader first (parent last)’
  5. Choose ‘Single class loader for application’
  6. Select OK -> Save

Configuration in WebLogic

Deploy the WAR File

To use the deployment wizard in WebLogic to deploy the WAR file:

  1. Click Deployments
  2. In the Deployments table, click Install.
  3. Enter the path to the WAR file and then select the WAR file from the list.
  4. Select Install this deployment as an application.
  5. Select Custom Roles: Use roles that are defined in the Administration Console; use policies that are defined in the deployment descriptor. Selecting this option allows you to manage the roles and users in WebLogic’s administration console, while WebLogic loads the roles and policies defined in the application.

Allow Access to WebLogic Users

After deploying, allow WebLogic users to access the application:

  1. In the WebLogic administration console, click Deployments. In the Deployments table, click the name for the application.
  2. Click Security > Application Scope > Roles > New.
  3. Add the arcesb_admin Web Application Scoped role and assign the role to a user or group who administers the application.

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

Configuration in Jetty

While Arc comes with an embedded Jetty web server, the application can also be used with an external Jetty setup.

Deploy the WAR File

Copy the WAR file into Jetty’s webapps folder.

Allow Access to Jetty Users

Before starting Jetty, allow Jetty users to access the application by assigning the arcesb_admin role. For example, you can add this role to the admin user by opening the JETTY_HOME/etc/realm.properties file. The properties for the user are composed of the password, followed by the user’s roles. For example:

admin: test,server-administrator,content-administrator,admin,user,arcesb_admin

Configure the Login Service for the Java Realm

You must also configure a login service for the application with the name ArcESBRealm. Below is a HashLoginService example:

<Call name="addBean">
  <Arg>
    <New class="org.eclipse.jetty.security.HashLoginService">
      <Set name="name">ArcESBRealm</Set>
      <Set name="config"><Property name="jetty.home" default="."/>/etc/realm.properties</Set>
    </New>
  </Arg>
</Call>

Configure Data Directory Permissions

Allow the user of the process running the Java servlet container read/write access to the data directory:

  • Windows: C:\\ProgramData\\ArcESB\\
  • Unix or Mac OS X: ~/arcesb/

Restart the server and log into the application.

User Management

The Java version of the Arc web application uses forms authentication.

In Java, the user roles and passwords are managed in the Java realm configuration for your web server. Refer to your web server’s documentation from how to configure a user’s roles and password. The application requires the arcesb_admin role.

Find and Configure the Application Directory

Arc’s Application Directory holds all of the data used by the application: configuration data, application data, logging data, certificates, etc. The default location of the Application Directory depends on whether Arc is hosted via the embedded web server or an external Java servlet container.

For the embedded web server, the Application Directory is the same as the installation directory, which by default is the following:

/opt/arcesb

When hosting Arc in an external Java servlet container, the Application Directory is relative to the home directory of the user running the server:

~/arcesb (where ‘~’ resolves to the home directory of the user running the server hosting the application)

The Application Directory folder can be configured, which is useful in a variety of scenarios:

  • Clustering multiple instances of Arc
  • Using a shared network drive for application data
  • Embed Arc within other systems accessing the same folders

Changing the Application Directory will move the application’s data files but will not move other application resources like .exe’s, .jar’s, etc. These resources are held in the Installation Directory, which may be the same as the Application Directory but will not change if the Application Directory is changed.

Embedded Java Server

When using the Java edition with the embedded Jetty server, the application database is configured in the arcesb.xml file found in the Installation Directory. Within this server configuration file, the AppDirectory environment variable must be set to the path to the desired directory. The following example demonstrates what this might look like when setting the data directory to a shared folder on a mounted drive:

<Call name="setInitParameter">
  <Arg>AppDirectory</Arg>
  <Arg>/mnt/shared/arcesb</Arg>
</Call>

If Arc can find the path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.

External Java Server

When using the Java edition with an external Java servlet (any server other than the Jetty server that is included with the application), the details of configuring the application data directory depend upon the specific servlet used. Using the syntax appropriate for the specific servlet, the AppDirectory environment variable must be set to the path to the desired directory.

If Arc can find the AppDirectory path, and has the appropriate permissions to read and write at the given path, it will create the data folder within the specified directory.

Configure the Application Database

Arc’s Application Database stores several tables of application data, including:

  • Transaction Log (metadata for each transaction processed by the application)
  • Application Log (application-level errors and events)
  • Access Log (requests to the application’s web endpoint)

By default, Arc uses a Derby database located in the Application Directory as the Application Database, but this can be configured to use an enterprise database like MySQL or SQL Server.

Embedded Java Server

When using the Java edition with the embedded Jetty server, the application database is configured in the arcesb.xml file found in the installation directory. Within this server configuration file, the APP_DB environment variable must be set to a JDBC connection string containing the appropriate connection parameters for the desired database. For example:

<Call name="setInitParameter">
  <Arg>APP_DB</Arg>
  <Arg>jdbc:mysql:Server=MySQLServer;Port=3306;Database=mysql;User=user;Password=password</Arg>
</Call>

If Arc can successfully establish a connection with the APP_DB connection string, it will use that database as the application database.

External Java Server

When using the Java edition with an external Java servlet (any server other than the Jetty server that is included with the application), the details of configuring the application database depend upon the specific servlet used. Using the syntax appropriate for the specific servlet, one of the following approaches should be used when configuring the server:

  • Define a JNDI datasource to include the connection properties for the target database.
  • Set the APP_DB environment variable to a JDBC connection string.

If Arc can use the JDNI datasource or APP_DB connection string to connect to a database, it will use that database as the application database.