BlazeDS Installation Guide

BlazeDS runs in a J2EE web application and is available in ZIP files for the following configurations:

• BlazeDS with integrated Apache Tomcat application server
• BlazeDS web applications

BlazeDS runs on the following platforms:

• Windows
• Linux
• Solaris

These installation instructions refer to root directory where you unzip the BlazeDS ZIP file as install_root.

BlazeDS includes the following Web Application Archive (WAR) files:

• blazeds.war - The primary BlazeDS WAR file: use this as a starting point for building your BlazeDS application.
• samples.war - Sample BlazeDS applications.
• ds-console.war - Simple monitoring application for BlazeDS deployments.

Each WAR file is a separate, stand-alone web application. If you are using the J2EE web application option, you must have an existing J2EE application server or servlet container available and understand web application deployment. If you do not have an existing J2EE server or are not familiar with WAR file deployment, use the integrated Tomcat configuration to get started.
BlazeDS with integrated Tomcat

The BlazeDS with integrated Tomcat ZIP file contains the following files and directories under the installation root:

• readme.htm - Contains an overview of important information.
• blazeds.war - BlazeDS web application, used as a starting point for new applications.
• samples.war - BlazeDS sample applications.
• ds-console.war - Simple monitoring application for BlazeDS deployments.
• license.txt - Contains license information.
• /tomcat - Contains an installation of Apache Tomcat that includes blazeds, samples, and ds-console web applications expanded and deployed in the default server.
• /resources - Contains Flex SDK source code, fully commented configuration files, as well as directories and files used for security, clustering, Flex Ajax Bridge and manually creating HTML wrappers. Flash Player installers are in the Flex SDK ZIP file.

To install BlazeDS in the integrated Tomcat configuration:

1. Read the BlazeDS release notes for known issues and any late-breaking information.
2. Unzip the ZIP file to a local directory on your file system.
3. Make sure that the machine you are installing on has a Java Development Kit (JDK) installed and a JAVA_HOME environment variable.
4. To start BlazeDS, open a command window, navigate to install_root/tomcat/bin, and enter the catalina start command. On UNIX and Linux, enter ./catalina start. Optionally, on Windows you can navigate to the install_root/tomcat/bin in Windows Explorer and double-click the catalina.bat icon.
5. The BlazeDS sample applications use an HSQLDB database that is installed in the install_root/sampledb directory. To start the sample database:
   • Open a command prompt and go to the install_root/sampledb directory.
   • Run startdb.bat (Windows) or startdb.sh (Unix-based systems).

Running the Test Drive with the integrated Tomcat install

In addition to the BlazeDS WAR file, the BlazeDS download includes a version of Tomcat (6.0.14) with a series of web applications fully configured with BlazeDS (including blazeds-sample). To run the test drive after downloading and expanding the integrated Tomcat install:

1. Start Tomcat (startup.bat or startup.sh in /blazeds/tomcat/bin).
2. Open a browser and access the samples home page:
   http://localhost:8400/samples/
3. Take the test drive!

BlazeDS J2EE web applications

The BlazeDS J2EE web application option installs the following files and directories under the installation root:

• readme.htm - Contains an overview of important information.
• blazeds.war - BlazeDS web application, used as a starting point for new applications.
• samples.war - BlazeDS sample applications.
• ds-console.war - Simple monitoring application for BlazeDS deployments.
• license.txt - Contains license information.
• /resources - Contains Flex SDK source code, fully commented configuration files, as well as directories and files used for security, clustering, Flex-Ajax Bridge and manually creating HTML wrappers. Flash Player installers are in the Flex SDK ZIP file.

To install BlazeDS as a J2EE web application:

1. Read the BlazeDS Release Notes for known issues and any late-breaking information.
2. Unzip the BlazeDS ZIP file.
3. Deploy the blazeds, samples, and ds-console web applications by using your application-server-specific deployment method. For example, for Tomcat, copy the WAR files to the webapps directory and restart the server.
4. The BlazeDS sample applications use an HSQLDB database that is installed in the install_root/sampledb directory. To start the sample database:
   • Open a command prompt and go to the install_root/sampledb directory.
   • Run startdb.bat (Windows) or startdb.sh (Unix-based systems).
5. Perform additional application-server specific configuration, as described in Additional server-specific configuration.

Additional server-specific configuration

You may need to perform additional configuration steps for the following application servers:

• Tomcat 6
• WebSphere 6
• JBoss
• Running from a compressed WAR
• Integrating BlazeDS with a ColdFusion 8 installation

Tomcat

To use BlazeDS with Tomcat, follow these steps after deploying the BlazeDS WAR files. These steps are not necessary for the integrated Tomcat installation.

1. Increase the maximum memory to at least 512MB. This is achieved by specifying the maximum heap size for the JVM in the JAVA_OPTS variable: -Xmx512m
2. (Optional) To enable custom authentication, locate the Tomcat security resource libraries under install_root/resources/security/tomcat.
   1. Put flex-tomcat-common.jar in tomcat/lib/blazeds.
   2. Place flex-tomcat-server.jar in tomcat/lib/blazeds.
   3. Edit the catalina.properties file which can be found in the tomcat/conf directory. Find the common.loader property and add the following path to the end of the list: ${catalina.home}/lib/blazeds/*.jar
   4. Add <Valve className="flex.messaging.security.TomcatValve"/> tag to the Context descriptors. For example, for the BlazeDS samples WAR:
      <Context path="/samples" docBase="${catalina.home}/webapps/samples" debug="0">
      <Valve className="flex.messaging.security.TomcatValve"/>
      </Context>
      You will now be authenticated against the current Tomcat realm. Usually, the default for this authentication stores user information in conf/tomcat-users.xml. See the Tomcat documentation for more information on realms. See the documentation for more information on BlazeDS custom authentication.
   5. You may also need to update the active <login-command> in /WEB-INF/flex/services-config.xml
      in each deployment of a BlazeDS WAR file. For Tomcat, ensure that the TomcatLoginCommand is active in the <security> section:
      <security>
      <login-command class="flex.messaging.security.TomcatLoginCommand" server="Tomcat" />
      ...
3. (Optional) To use the JMSAdapter with the Message Service, you must install and configure a JMS provider (such as activeMQ or openJMS) for use with Tomcat.
4. Restart Tomcat.

Configuring ActiveMQ 4.1.1 with Tomcat 6.0.x

These instructions create a configuration that matches what is distributed with BlazeDS. You should be able to integrate Apache ActiveMQ 4.1.1 with earlier versions of Tomcat and you should also be able to integrate newer versions of ActiveMQ with Tomcat 6.0.x, but none of these configurations have been tested. These instructions require that you have a valid Apache Ant installation.

Complete the following steps to integrate ActiveMQ with your own installation of Tomcat 6.0.x:

1. Download ActiveMQ 4.1.1 from http://activemq.apache.org.
2. Download and install the ActiveMQ distribution following the instructions provided on the ActiveMQ website.
3. ActiveMQ ships with an example that contains the JAR files and configuration settings that work with a web application deployment. Build the example by opening a command prompt, changing to the activemq_root/example directory and running the following command to build the example:
   ant war
4. In the tomcat_root/lib directory, create a new directory called activemq4.1.1. Copy the contents of the activemq_root/example/target/activemq-web/WEB-INF/lib directory to this new directory.
5. Open the catalina.properties file from the tomcat_install/conf directory in a text editor. Modify the common.loader property by adding the following to the list of comma-seperated paths:
   ${catalina.home}/lib/activemq4.1.1/*.jar
6. Modify your BlazeDS web application to start an ActiveMQ message broker when the web application starts. To do this, open the WEB-INF/web.xml file for your web application in a text editor. Add the following context-param and listener elements. Make sure you put them in the correct location within the web.xml. The order of these must match the web-app dtd.

   <context-param>
       <param-name>brokerURI</param-name>
   
       <param-value>/WEB-INF/activemq.xml</param-value>
   </context-param>
   
   <listener>
       <listener-class>org.apache.activemq.web.SpringBrokerContextListener</listener-class>
   </listener>
   

7. In the WEB-INF directory of your web application create a new file called activemq.xml. Open the file in a text editor and add the following text:

   <?xml version="1.0" encoding="UTF-8"?>
   <beans>
   	<broker useJmx="true" persistent="false" xmlns="http://activemq.org/config/1.0" brokerName="myBroker">
   
   		<transportConnectors>
   			<transportConnector name="default" uri="tcp://localhost:61716"/>
   		</transportConnectors>
   	</broker>
   </beans>
   

   This starts an ActiveMQ message broker with a broker name of myBroker listening for requests on the localhost network interface at port 61716.

8. Add the ActiveMQ connection factories and any JMS Topics and Queues you want to use to JNDI. The easiest way to do this in Tomcat 6.0.x is to create a context file for your web application and put the settings in there. To do this, create a new file in the tomcat_install/conf/Catalina/localhost directory. If the Catalina/localhost directory does not exit already create it now. The new file that you create should have the same name as the web application with a .xml extension. For example, if your BlazeDS web application is named samples the Tomcat context file should be named samples.xml. For more information on context files, refer to your Tomcat documentation. Once you have created the file, open it in a text editor. Add the following contents to the file, replacing the example topic and queue shown here with your own topics and queues:

   <Context privileged="true" antiResourceLocking="false" antiJARLocking="false" reloadable="true">
   
       <Resource name="jms/flex/TopicConnectionFactory"
                   type="org.apache.activemq.ActiveMQConnectionFactory"
                   description="JMS Connection Factory"
                   factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                   brokerURL="tcp://localhost:61716"
   
                   brokerName="myBroker"/>
    	<Resource name="jms/topic/flex/simpletopic"
                   type="org.apache.activemq.command.ActiveMQTopic"
                   description="my Topic"
   
                   factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                   physicalName="FlexTopic"/>
   	<Resource name="jms/flex/QueueConnectionFactory"
                   type="org.apache.activemq.ActiveMQConnectionFactory"
   
                   description="JMS Connection Factory"
                   factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                   brokerURL="tcp://localhost:61716"
                   brokerName="myBroker"/>
   
       <Resource name="jms/queue/flex/simplequeue"
                   type="org.apache.activemq.command.ActiveMQQueue"
                   description="my Queue"
                   factory="org.apache.activemq.jndi.JNDIReferenceFactory"
                   physicalName="FlexQueue"/>                
       <Valve className="flex.messaging.security.TomcatValve"/>
   
   </Context>
   

9. Start your Tomcat server. The ActiveMQ message broker should start listening for messages on port 61716 and you should be able to send messages to and receive message from the JMS topics and queues you have configured. For more information about configuring and using ActiveMQ, please refer to the ActiveMQ documentation which is available on http://activemq.apache.org.

WebSphere

(Optional) To enable custom authentication, open the WebSphere Administrator and configure a custom user registry using the files under install_root/resources/security/websphere/ as usersFile and groupsFile custom properties.

JBoss

(Optional) To enable custom authentication, you must perform the following configuration steps:

1. Put install_root/resources/security/tomcat/flex-tomcat-common.jar and install_root/resources/security/tomcat/flex-tomcat-server.jar in the jboss_root/server/default/lib folder.
2. Add <Valve className="flex.messaging.security.TomcatValve"/> tag to the Context descriptors.
3. Restart JBoss.

This configuration provides authentication against the current JBoss realm. Usually, the default for this authentication stores user information in jboss_root/server/default/conf/users.properties and roles information in jboss_root/server/default/conf/roles.properties. For more information on realms, see the JBoss documentation. For more information on BlazeDS custom authentication, see the BlazeDS documentation and information in the install_root/resources/security directory.
Running from a compressed WAR

To run BlazeDS from a compressed WAR file, perform the following steps:

1. Expand the flex.war file using winzip or the JAR utility.
2. Create your application, including SWF files, ActionScript files, configuration settings and HTML wrappers.
   Note: For more information on compiling SWF files and creating HTML wrappers, see the BlazeDS documentation.
3. Create a compressed WAR file from the expanded web application structure.
4. Deploy the compressed WAR file.
   Note that many samples applications in samples.war use HSQLDB which will not function within a compressed web application. It is therefore advised to deploy samples as an uncompressed war.
   Note that when running BlazeDS from a compressed WAR file some features, such as clustering are not available.

Integrating BlazeDS with a ColdFusion 8 installation

To integrate BlazeDS with ColdFusion 8 with integrated LiveCycle Data Services ES installation, perform these steps:

1. Shut down ColdFusion.
2. Move aside the ColdFusion8/wwwroot/WEB-INF/flex directory.
3. Edit ColdFusion8/WEB-INF/web.xml:
   • Comment out/remove the definitions of FlexMxmlServlet and FlexInternalServlet servlets.
   • Comment out/remove the servlet mapping for FlexMxmlServlet and FlexInternalServlet.
   • Comment out/remove the taglig definition for the FlexTagLib tag library.
4. Complete the following instructions for ColdFusion without Integrated LiveCycle Data Services ES.

To integrate BlazeDS with ColdFusion 8 without integrated LiveCycle Data Services ES installation, perform these steps:

1. Shut down ColdFusion.
2. Unzip blazeds.war in to a temporary directory (In this example c:\temp\BlazeDS).
3. Move aside the following jar files from ColdFusion8/lib:
   • flex-messaging.jar
   • flex-messaging-common.jar
   • flex-messaging-opt.jar
   • flex-messaging-req.jar
4. Copy the following jar files from c:\temp\BlazeDS\WEB-INF\lib to ColdFusion8/lib:
   • flex-messaging-common.jar
   • flex-messaging-core.jar
   • flex-messaging-opt.jar
   • flex-messaging-proxy.jar
   • flex-messaging-remoting.jar
5. Create a new directory (create the WEB-INF/flex directory if needed):
   ColdFusion8/wwwroot/WEB-INF/flex/jars
6. Copy the following jar files from c:\temp\BlazeDS\WEB-INF\lib to ColdFusion8/wwwroot/WEB-INF/flex/jars:
   • concurrent.jar
   • cfgatewayadapter
7. Set up the configuration files for BlazeDS. You can copy the set of configuration files from the BlazeDS ZIP file (not the WAR file). Copy the following files in resources/ColdFusion to ColdFusion8/wwwroot/WEB-INF/flex:
   • services-config.xml
   • messaging-config.xml
   • proxy-config.xml
   • remoting-config.xml
     (Optional)
     You can continue to use the configuration files from your integrated LiveCycle Data Services ES installation by doing the following:
8. Copy services-config.xml, messaging-config.xml, proxy-config.xml, and remoting-config.xml from the WEB-INF/flex directory you moved aside earlier back to ColdFusion8/wwwroot/WEB-INF/flex.
9. Remove from the following line from the services-config.xml file:
   <service-include file-path="data-management-config.xml" />
10. Remove the <channel-definition> for the ColdFusion-specific RTMP channel (if not commented out) and remove the java-http and java-secure-http channel definitions.
11. Uncomment the java-amf, java-secure-amf and java-polling-amf channels. Do not include the java-rtmp channel definition.
12. Edit the proxy-config.xml file and change the lines:
    <channel ref="java-http"/>
    <!-- <channel ref="java-amf"/> -->
    to the following text:
    <channel ref="java-amf"/>