docs.intersystems.com
Home  /  Application Development: Using Adapters and Gateways in Productions  /  Developing Productions with Java Business Services and Operations  /  Sample Code Walkthrough


Developing Productions with Java Business Services and Operations
Sample Code Walkthrough
[Back] 
InterSystems: The power behind what matters   
Search:  


The sample Java Business Service and Java Business Operation demonstrates how to send a message from a business service written in Java into a production and how to send a message from a production to a business operation written in Java.
This chapter contains the following sections:
Note:
This walkthrough uses the JDK development environment on Windows. You can develop Java Business Services and Operations in any Java development environment on any platform, but the procedure to create the jar files may be different in your environment. This walkthrough assumes you have installed InterSystems IRIS™ and the Java JDK or another Java development environment on your system.
Overview of the Sample Code
The hello Java sample code provides a very simple example of a Java business service and a Java business operation.
The hello Java sample source files are provided in:
install-directory\dev\java\samples\gateway\hello
The jar files that define the Java classes used to implement Java business services and operations are provided in the following files, for the JDK versions 1.7 and 1.8, respectively:
install-dir\dev\java\lib\JDK17\isc-gateway-2.0.0.jar
install-dir\dev\java\lib\JDK18\isc-gateway-2.0.0.jar
Getting the Environment Ready
In order to generate the components needed to use the Java business service and operation sample, you must first:
After starting the production and defining the credentials, you will next compile the Java code and generate the jar files, which is described in the next section.
Starting the Production
To start a production with the gateway initiator, you will perform the following steps:
  1. Select a production-enabled namespace or create a new one.
  2. Create a new production in that namespace.
  3. Add the initiator business service component.
  4. Configure the initiator.
  5. Start the production.
The detailed steps to start the production follow:
  1. Select a production-enabled namespace or create a new one. If you select an existing namespace, go to step 2. If you are creating a new namespace:
    1. Select System Administration > Configuration > System Configuration > Namespaces to get to the Namespaces portal page.
    2. Select the Create New Namespace button, specify a name for the namespace, such as JAVAHNS.
    3. Select the Create New Database button for the globals database.
    4. In the Database Wizard, enter a name for the globals database, such as JAVAHNS_GDB. The wizard uses the name to create a directory for the database. Select Next and then Finish to create the database.
    5. Repeat steps c through d for the routines database, using a name such as JAVAHNS_RDB.
    6. Select the Save button to complete creating the namespace.
    7. Select Close to close the log.
  2. Create a new production in the namespace:
    1. Select Interoperability > List > Productions and select New to create the new namespace.
    2. Specify a package name, production name, and select the generic Production Type.
    3. Select OK.
  3. Add the initiator business service component:
    1. Select the + (plus sign) for adding Services.
    2. On the All Services tab select the EnsLib.JavaGateway.Initiator service. Do not enable it yet.
  4. Configure the initiator:
    1. Select the EnsLib.JavaGateway.Initiator service in the production diagram.
    2. In the Settings tab, check the Enable check box.
    3. In the Additional Settings group, set Java Home to the location of the Java runtime and JDK installation. On Windows, this is typically the value of the JAVA_HOME environment variable. A typical value is C:\Program Files\Java\jdk1.8.0_92.
    4. Also in the Additional Settings group, set JDK Version to the version number of your Java installation.
    5. Select the Apply button.
  5. Start the production by selecting the Start button.
Defining the Credentials
The credentials are used by the Java code in the business service to log into InterSystems IRIS. To create the credentials:
  1. Enter any ID, such as hello_user.
  2. Enter aUser Name and Password that provide access to InterSystems IRIS.
  3. Select Save.
Compiling Java Code and Creating Jar Files
This procedure demonstrates how to compile the Java business service, helloBS.java, and the business operation, helloBO.java, and then produce a jar file for each using the JDK:
  1. Ensure that the Java compiler has access to the jar file that defines the Java classes used for Java business services and operations. On Windows, you can do this by adding the following to the CLASSPATH environment variable:
    If you have Java version 1.7, use the JDK17 folder instead of JDK18.
  2. Copy the helloBS.java and helloBO.java files from the install directory to another directory.
  3. In this other directory, create two subdirectories for the output of the compiler for the business service and operation. For example:
  4. Use the JDK jar utility to create a jar file for the business service and another jar file for the business operation:
Generating Java Business Service and Operation
This procedure demonstrates how to generate the components that communicate with your Java business service and business operation. To generate the components for the sample code:
  1. Before generating the components, you must be in a namespace with a running production that includes the Java Gateway initiator. See Starting the Production.
  2. Specify the Path to the JAR file for the helloBS.jar generated in the previous section.
  3. Specify a name for the ObjectScript Class. For example, you can specify hello.BS.
  4. Select the Business Service radio button.
  5. Select Generate.
  6. Repeat these steps for the business operation, specifying the path to the helloBO.jar file, hello.helloBO for the Java class name, and hello.BO for the ObjectScript class name. Select the Business Operation radio button and select Generate.
Creating and Configuring the Production
A production that runs the Java sample code contains the following components:
You can use the production you created in the Starting a Production step or you can create a new production. To create and configure the production:
  1. From the production list, open the production you created in Starting a Production or create a new production.
  2. If the production is running, stop the production.
  3. If you have created a new production, add the EnsLib.JavaGateway.Initiator business service and configure it as described in Starting a Production.
  4. Select the + (plus sign) for adding Operations. Select the class you generated for the Java business service, such as hello.BO. You can optionally specify a name for the operation and a comment. Do not select the Enable Now check box. Select OK.
  5. Configure the generated business operation:
    1. Select the generated business operation, such as hello.BO, in the production diagram.
    2. In the Basic Settings group, select the Enabled check box.
    3. In the Additional Settings group, enter a file specification in the LogFile field.
    4. Select Apply
  6. Select the + (plus sign) for adding Services. Select the class you generated for the Java business service, such as hello.BS. You can optionally specify a name. Specify a comment. Do not select the Enable Now check box. Select OK.
  7. Configure the generated business service:
    1. Select the generated business service, such as hello.BS, in the production diagram.
    2. In the Informational Settings group, enter a Comment.
    3. In the Basic Settings group, select the Enabled check box and select the generated business operation, such as hello.BO from the Target Config Names drop-down menu.
    4. In the Additional Settings group, select the Credentials drop-down menu and select the credentials that you defined in Defining the Credentials. You can also optionally specify the Min and Max values. The default values are 0 and 100. These control the values of the random numbers generated in the messages.
    5. Select Apply
Running the Production
To run and explore the production, follow these steps:
  1. Select the Start button.
  2. All of the components in the production should be shown with green circles indicating they are running correctly. If any component is red, see Troubleshooting the Sample.