Web-module binding

This article explains how to bind an archived or unarchived Web-module to an existing Site on an Orion Application Server, manually or by usage of the Console on the Orion Application Server.

Introduction
Binding an Web-module manually
Binding a Web-module through admin.jar
Binding a Web-module through Ant

1 Introduction

    This article will explain how to bind a Web-module to an existing Site on an Orion Application Server by presenting a step-by-step guide for various situations. Information about deploying Web-modules can be found here.

    Any Web-module can be bound to one or more Sites one or more times as long as they are bound to a unique context root on a certain Site.

2 Binding an Web-module manually

    This section describes the steps necessary to bind a Web-module to an existing site.

    This section involves the following steps:

    Step 1: Adding Web-module to default application (optional)
    Step 2: Bind Web-module to site

    2.1 Step 1: Adding Web-module to default application (optional)

      If the Web-module is not part of a J2EE application you can add it to the default application shipped with Orion.

      Step-by-step instructions for adding a stand-alone Web-module can be found here .

    2.2 Step 2: Bind Web-module to site

      In order for a Web-module to be accessible by clients, it needs to be bound to a site.

      Add an entry like the one given below to the web-site.xml file of the Site to deploy to: 


          <web-app
              application="application-name"
              load-on-startup="boolean1"
              max-inactivity-time="minutes"
              name="name"
              root="root"
              shared="boolean2" />

      The syntax of the web-app tag can be found here.

      Replace application-name with the reference name of the application containing the Web-module, such as "atm".

      Replace boolean1 with either true or false depending upon if you the web-module should be pre-loaded or not. If false, the Web-module will be loaded when a client access it for the first time. The default value is false, so the attribute only needs to be stated when setting the value to true.

      Replace max-inactivity-time with the number of minutes of inactivity that can precede a shutdown of the web-application. If this attribute is not given, no shut-down will occur. The default is that the attribute is not given.

      Replace name with the URI of the Web-module as it is stated in the Applications application.xml file. If the Web-module is packaged into a WAR, it's the URI of the WAR file without the .war suffix.

      Replace root with the URI that the Web-module should be bound to on the Site, such as "/atm-web". In order for a client to access this Web-module, it would use a URL such as "http://hostname/atm-web".

      Replace boolean2 with either true or false. Giving the attribute a value of true would imply that the web-modules Sessions and Servlet instances should be shared with other Web-modules who also got a value of true for the shared attribute. Giving the attribute a value of false would imply that the Web-modules Sessions and Servlet instances should not be shared with other Web-modules. The default value is false. This attribute has only to be given when it's value is to be set to true.

      If deploying to the default web Site, web-site.xml can normally be found at /orion/config/default-web-site.xml

      Shared is commonly used for sharing Sessions between SSL protected sites and unprotected sites, as Internet Explorer doesn't handle SSL Sessions correctly. Notice that this leads to a lower degree of security.

      When a Web-module is bound to a Site, the Server hosting the Site outputs a confirmation (or an error message) to Standard.out. It also creates a new directory in the applications deployment directory for the Web-module.

3 Binding a Web-module through admin.jar

    This section describes the steps necessary to bind a Web-module to an existing site through usage of the Orion admin.jar.

    One of the benefits of using the admin.jar over manually binding an Web-module is that it allows this to be performed remotely. The admin.jar approach does not involve a GUI, which could be good for environments where none is available. The downside is that the Web-module needs to be archived as a WAR-archive.

    Notice that the Application that the Web-module is part of must already been deployed to a Host in order binding to be possible.

    Step-by-step instructions for deploying an Application can be found here.

    This section involves the following steps:

    Step 1: Bind Web-module to site

    3.1 Step 1: Bind Web-module to site

      Go through this step to bind a Web-module to an existing site.

      Issue the following command to bind a Web-module: 


      java -jar admin.jar ormi://host:port username password -bindWebApp deploymentName web-app web-site root

      Replace host with the location of the host to deploy to.

      Replace port with the port the host is listening to. If not specified 23791 will be used by default.

      Replace username with a valid administrator username.

      Replace password with a valid administrator password that belongs to the given username (see above).

      Replace deploymentName with the deployment name of the Application that the Web-module is part of.

      Replace web-app with the name of the Web-module to bind.

      Replace web-site with the name of the Site to bind the Web-module to such as "default-web-site".

      If the specified Site does not exist, Orion will return an error message containing the names of the active Sites.

      Replace root with the context root that the Web-module should be bound to on the Site, such as "/atm-web". In order for a client to access this Web-module, he would use a URL such as "http://hostname/atm-web".

4 Binding a Web-module through Ant

    This section describes the steps necessary to bind a Web-module to an existing Site through the usage of Ant.

    This can be particularly useful during development when builds containing Web-modules has to be deployed to different Sites in an orderly and controlled way.

    One of the benefits of using the Ant approach over manually binding a Web-module is that it allows this to be performed remote. The Ant approach does not involve a GUI, which could be good for environments where none is available. The downside is that the Web-module needs to be archived as a WAR-archive, but this is very simple to do when utilizing Ant.

    Notice that the Application that the Web-module is part of must already been deployed to a Host in order binding to be possible.

    Step-by-step instructions for deploying an Application can be found here.

    In order to utilize this section, Ant knowledge is required. Read more about Ant here.

    This section involves the following steps:

    Step 1: Creating the build file
    Step 2: Executing the build file

    4.1 Step 1: Creating the build file

      In a suitable directory, create the following build file and call it build.xml:


          <?xml version="1.0" ?>
          <project name="hello-world" default="bind" basedir=".">
              <target name="init">
                  <property name="bind.appDeployName" value="hello-world" />
                  <property name="bind.webAppName" value="hello-web" />
                  <property name="bind.webSiteName" value="default-web-site" />
                  <property name="bind.root" value="/hello" />
                  <property name="orion.dir" value="/usr/local/orion" />
                  <property name="build.compiler" value="classic" />
                  <property name="deploy.ormi" value="" />
                  <property name="deploy.username" value="" />
                  <property name="deploy.password" value="" />
              </target>
              <target name="bind" depends="init">
                  <java classname="com.evermind.client.orion.OrionConsoleAdmin" fork="yes">
                      <arg value="${deploy.ormi}" />
                      <arg value="${deploy.username}" />
                      <arg value="${deploy.password}" />
                      <arg value="-bindWebApp" />
                      <arg value="${bind.appDeployName}" />
                      <arg value="${bind.webAppName}" />
                      <arg value="${bind.webSiteName}" />
                      <arg value="${bind.root}" />
                      <classpath>
                          <pathelement location="${orion.dir}/orion.jar" />
                          <pathelement location="${orion.dir}/ejb.jar" />
                          <pathelement location="${orion.dir}/jndi.jar" />
                      </classpath>
                  </java>
              </target>
          </project>

      Replace the value of the property bind.appDeployName with the reference name of the application containing the Web-module, such as "atm".

      Replace the value of the property bind.webAppName with the name of the Web-module to bind, such as "atm-web".

      Replace the value of the property bind.webSiteName with the name of the web-site to bind the Web-module to, such as "default-web-site".

      If the specified Site does not exist, Orion will return an error message containing the names of the active sites.

      Replace the value of the property bind.root with the context root that the Web-module should be bound to on the Site, such as "/atm-web". In order for a client to access this Web-module, it would use a URL such as "http://[hostname]/atm-web".

      Replace the value of the property orion.dir with the path to the directory holding your Orion JAR files.

      Replace the value of the property build.compiler with the compiler to use (if you don't want to use classic).

      Replace the value of the property deploy.ormi with the path to the Orion Application Server to deploy to.

      Replace the value of the property deploy.username with the name of an administrator user on the Orion Application Server to deploy to.

      Replace the value of the property deploy.password with the password of an administrator user on the Orion Application Server to deploy to.

      If no build file name is specified, Ant will look for a file called build.xml.

    4.2 Step 2: Executing the build file

      In a suitable directory (depending on your setup) execute the build file with the following command:


      ant

      If the build file is not located in the same directory as Ant is executed in, the -buildFile [file] needs to be utilized to point out the build file to use.

      This will invoke Ant looking for a local build.xml file. As the build.xml file created above has a default target, there is no reason to specify a target.

      The specified Web-module should now be bound to the specified Site.

Copyright 2003 IronFlare AB