Installing and Running the ALF Runtime

Note: These instructions apply to the following version of the ALF Runtime only

ALF1_0M7-2007-02-23-0008.zip

installed on the Windows 2003 operating system.

Prerequisite:

Ensure the following are installed.

· Java 1.4.2 or later

· Tomcat 5.5.x,

· Eclipse 2.3 with WTP 1.5.2 ("all-in-one" package recommended)

· Jdom.jar 1.0

Installation Instructions

Download and extract the runtime .zip file. The .zip file contains the folder ALFRuntime which contains the following components:

· org.eclipse.alf_1.0.0 folder

· ALFEventManager.war

· ALFEventEmitter folder

· ALFHOME folder

· TestALFService.war

· TestALFConfig folder

ALF_HOME and the ALF_HOME Enviroment Variable

ALF_HOME is a common location where all ALF related files such as deployed files, configuration files are stored. ALF_HOME is identified tot eh system via a "system" environment variable named "ALF_HOME" the value of which is the path to the ALF_HOME folder.

ALF_HOME should contain:

· deploy - a folder

· alf.properties – configuration properties for the alf event manager. You should not need to change these unless you are configuring an alternative Common Logging Services

· alf_log4j.properties - logging configuration for both alf event manager diagnostic logging and the default implementation of the Common Logging Service (see below)

The folder “deploy” should contain:

· ApplicationStatus.xml - a file that records the status of the currently deployed ALF applications

· TestALFConfig1.alf - and example ALF event-action map

Copy the provided ALF_HOME folder to some appropriate location on the target machine eg C:\ALF_HOME

Set a "system" Environment Variable named ALF_HOME to point to that location.

alf_log4j.properties

IMPORTANT: The logging configuration file, alf_log4j.properties, is setup to log to the current directory of the runtime environment. This assumes nothing about the installation but is probably not the most convenient for finding the logs. The location depends on your environment so you may have search for the file. For a default install of Tomcat, the Tomcat “bin” folder appears to be the “current” folder. When running Tomcat under Eclipse within an Eclipse server project (see the WTP plugin) then the root Eclipse install folder appears to be the “current” folder.

It is suggested that you edit the alf_log4j.properties file and set the logging destination to the folder you have set up as ALF_HOME (eg. C:\ALF_HOME). For example, change these lines:

log4j.appender.LOGFILE1.File=ALFEventManager.log

log4j.appender.LOGFILE2.File=ALFCommonLogger.log

like this:

log4j.appender.LOGFILE1.File=C:\\ALF_HOME\\ALFEventManager.log

log4j.appender.LOGFILE2.File=C:\\ALF_HOME\\ALFCommonLogger.log

log4j Configuration Notes

The ALF Event Manager uses log4j for logging. The file “alf_log4j.properties” is a standard log4j properties file. This is a brief description of the configuration. Consult to the log4j documentation for specific command details.

The default configuration defines three loggers

log4j.rootLogger=INFO, CONSOLE, LOGFILE1

#log4j.logger.org.eclipse.alf=INFO, LOGFILE1

log4j.logger.org.eclipse.alf.logging=INFO, LOGFILE2

By default the logger “org.eclipse.alf” is commented out and all diagnostic messages, INFO and above, go to the rootLogger which will log to the CONSOLE and LOGFILE1 appenders (see below). To restrict the log to just messages from the ALFEventManager and to only log to the file, comment out the rootLogger as follows

#log4j.rootLogger=INFO, CONSOLE, LOGFILE1

and add the following line. (Note: You may just need to uncomment an existing line by removing the # )

log4j.logger.org.eclipse.alf=INFO, LOGFILE1

The default CommonLogger logging stream uses the LOGFILE2 logging stream which is set up to only log messages from the CommonLogging Service. Changing these settings this is not recommended unless you are replacing the CommonLogger with a different implementation (see the alf.properties file)

log4j.logger.org.eclipse.alf.logging=INFO, LOGFILE2

log4j.additivity.org.eclipse.alf.logging=false

Three appenders are defined as follows

log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender

log4j.appender.LOGFILE1=org.apache.log4j.RollingFileAppender

log4j.appender.LOGFILE2=org.apache.log4j.RollingFileAppender

By default all diagnostic logging messages go to both the CONSOLE and LOGFILE1. LOGFILE2 is uses exclusively by the CommonLogger which logs event data and data from calls to the Common Logging service.

Install the ALF Runtime on the Tomcat server

The install location of the Tomcat server is usually referenced by an environment variable named CATALINA_HOME. A example install directory might be:

C:\JAVA\apache-tomcat-5.5.17_8080

and in this case CATALINA_HOME would be set to the value C:\JAVA\apache-tomcat-5.5.17_8080

· Copy ALFEventManager.war to the CATALINA_HOME/webapps folder

· Copy TestALFService.war to the CATALINA_HOME/webapps folder

· Copy jdom.jar to CATALINA_HOME/common/lib

Test the Tomcat server install

Note: These instructions assume that the Tomcat server runs at the url "http://localhost:8080". If your install has a different url, substitute your location as appropriate.

Restart the Tomcat server.

In a web browser browse to

http://localhost:8080/ALFEventManager/services

This should display a web page that allows you to click a link to navigate to each of the following

http://localhost:8080/ALFEventManager/services/ALFEventManagerSOAP?wsdl

http://localhost:8080/ALFEventManager/services/ALFAdmin?wsdl

where you should see the WSDL for the respective service is displayed.

Similarly for the Test service, in a web browser browse to

http://localhost:8080/TestALFService/services

This should display a web page that allows you to click a link to navigate to

http://localhost:8080/TestALFService/services/ALFServiceFlowSOAP?wsdl

where you should see the WSDL for the service displayed.

Install the ALF Plugin into Eclipse

Find the folder where eclipse is installed. eg:

C:\JAVA\eclipse

This folder should contain a "plugins" folder. Remove any previous version of the ALFPlugin (eg:ALFPlugin1.0.0.jar)

Copy the folder

org.eclipse.alf_1.0.0

into the eclipse\plugins folder

Copy Jdom.jar to

org.eclipse.alf_1.0.0\lib

Restart eclipse.

Note: Eclipse command line options.

To force eclipse to re-load plugins it is sometimes necessary to run it with the "-clean" command line option.

Further it seems the WTP needs some adjustment to the default Java vm heap space by setting the "-Xmx512M" and "-XX:MaxPermSize=128M". A typical command line might be:

C:\JAVA\eclipse\eclipse.exe -clean -vm C:\Java\jdk1.5.0_07\bin\javaw -vmargs -Xmx512M -XX:MaxPermSize=128M

See eclipse and Java VM documentation for further details on these options

Import the TestALFConfig project into eclipse

Import the provided ALF project, TestALFConfig, into eclipse. To do this create a new “general” project and import the files from the TestALFConfig folder.

To create a new ALF Project

FileàNewàProjectàGeneralàproject

Choose Next and Enter the project name in the Text box and Finish.

This project is pre-configures with a simple ALF event map that utilizes the TestALFSevice and assumes that it is installed to a Tomcat server that runs at the default location

The TestALFConfig project contains:

· serverconfig.xml

· TestALFConfig.evt

· TestALFConfig.svc

· TestALFConfig1.alf

· TestALFConfig2.alf

The location of the ALF Sever is configured in "serverconfig.xml" found in the root project folder.

<Server>

<ServerName>ALFTest</ServerName>

<URL>http://localhost:8080/ALFEventManager/services/ALFAdmin</URL>

</Server>

You can edit this file as appropriate for you enviroment replacing "http://localhost:8080" with the root url for your Tomcat install.

The "TestALFConfig.evt File contains the registered ALF Events

The "TestALFConfig.svc File contains the registered ALF Service Flows. The TestALFService:

http://localhost:8080/TestALFService/services/ALFServiceFlowSOAP

provides a test example written as an axis service.

Note: Generally BPEL is recommended to implement Service Flows. Axis is used her to simplify the initial setup and test since ALF does not provide its own BPEL engine.

TestALFConfig1.alf and TestALFConfig2.alf are example ALF event-action maps ready to deployed to the ALF Event Manager. By default TestALFConfig1 is already installed in the provided ALF_HOME folder.

Now you can Test the Admin Functionalities by Deploying, UnDeploying etc from the Event-Action map editor window.

"Deploy", deploys the Application (.alf) File in ALF_HOME/deploy directory

Create a new ALF Project in Eclipse

Alternatively you can create new ALF Project by choosing the following Menu in Eclipse.

To create a new ALF Project

FileànewàProjectàAlfàALFProject

Choose Next and Enter the project name in the Text box and Finish.

This will create the .evt and .svc files. Use the .evt File to register your ALF Events. Use the .svc File to register your ALF Service Flows

To create .alf File (EventActionMap File) choose

· FileàNewàOtheràAlfàALFEventActionMap and click Next.

· Enter the Name of the Application to be deployed in the Text box and click Finish

ALFEventEmitter - Steps to Test the EventManager

The ALFEventEmitter folder contains the following

· ALFEventEmitter.jar

· ALFEventManager.jar

· axis.jar

· commons-discovery-0.2.jar

· commons-logging-1.0.4.jar

· jaxrpc.jar

· saaj.jar

· wsdl4j-1.5.1.jar

· log4j-1.2.8.jar

· Example_event.xml

· run.bat

ALFEventEmitter is a java library for emitting ALF events. It has a command line feature that allows it to emit an ALF event the content of which can be specified in the file. An example event file, Example_event.xml, is provided. And example windows .bat file, run.bat, is provide to illustrate the use o the command line option. This batch file assumes that the java jvm is available in the path and that the command is run from the same location as the ALFEventEmitter files

java -jar ALFEventEmitter.jar Example_event.xml http://localhost:8080/ALFEventManager/services/ALFEventManagerSOAP

The .jar file axis.jar is the core axis 1.3 library. The remaining .jars, commons-discovery-0.2.jar, commons-logging-1.0.4.jar, jaxrpc.jar, saaj.jar, and wsdl4j-1.5.1.jar are required by axis.