Menu ▾ ▴

BlazeDS 4.0 Installation Guide

Mayur Kansal SourceForge Editorial Staff Cory Johns

BlazeDS 4.0 Installation Guide

Contents

BlazeDS 4.0 Installation Guide
Installing BlazeDS with integrated Apache Tomcat application server (turnkey)
Installing BlazeDS with J2EE web applications
Additional server-specific configuration
Running BlazeDS from a compressed WAR file
Upgrading BlazeDS 3.2 to version 4.0

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

  • BlazeDS with integrated Apache Tomcat application server (turnkey)
  • 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.
  • blazeds-spring.war - An additional BlazeDS WAR file: use this as a starting point for building BlazeDS applictions using the Spring framework.
  • samples.war - Sample BlazeDS applications.
  • samples-spring.war - Samples BlazeDS application that integrates with the Spring framework. * 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. Note: for more information on the BlazeDS Spring integration see http://www.springsource.org/spring-flex.

Installing BlazeDS with integrated Apache Tomcat application server (turnkey)

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

  • blazeds_turnkey_readme.htm - Contains license information.
  • blazeds.war - BlazeDS web application, used as a starting point for new applications.
  • blazeds-spring.war - BlazeDS web application using Spring framework, used as a starting point for new application using the Spring framework.
  • samples.war - BlazeDS sample applications.
  • samples-spring.war - Samples BlazeDS application that integrates with the Spring framework.
  • ds-console.war - Simple monitoring application for BlazeDS deployments.
  • /docs - Contains the BlazeDS Javadocs.
  • /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.
  • /sampledb - Contains a sample HSQLDB database used with the integrated Apache Tomcat application server (turnkey)

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 blazeds-turnkey-4.0.<version>.zip file to a local directory on your file system. * Make sure that the machine you are installing on has a Java Development Kit (JDK) installed, JAVA_HOME environment variable set and (Windows only) the PATH environment variable updated to include JAVA_HOME/bin;. For Windows you can test your JDK environment variable configuration as follows:
    a. From a command prompt, type: cd JAVA_HOME/bin
    b. Next type: java -version
    c. The version of the JDK will be returned. If an error is returned, you must correct your environment variable settings before proceeding. </version>
  3. To start BlazeDS on Microssoft Windows, open a command window, navigate to install_root/tomcat/bin, and enter the catalina start command. On OS X, 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 startup.bat icon.

Running the Test Drive applications 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. There are two test drive applications:

Samples
Samples-spring

To run the test drive applications after downloading and expanding the integrated Tomcat install:

  1. Start Tomcat (startup.bat or startup.sh in /blazeds/tomcat/bin).
  2. 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).
  3. Open a browser and access one of the following sample home pages:
  4. http://localhost:8400/samples/
  5. http://localhost:8400/samples-spring/
  6. Take the test drive!

Installing BlazeDS with 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.
  • blazeds-spring.war - BlazeDS web application using Spring framework, used as a starting point for new application using the Spring framework.
  • samples.war - BlazeDS sample applications.
  • samples-spring.war - Samples BlazeDS application that integrates with the Spring framework.
  • 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. # Deploy the blazeds, samples, samples-spring.war, 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.
  3. The BlazeDS sample applications use an HSQLDB database that is installed in the install_root/sampledb directory. To start the sample database:
  4. Open a command prompt and go to the install_root/sampledb directory.

  5. Run startdb.bat (Windows) or startdb.sh (Unix-based systems).

  6. Perform additional application-server specific configuration, as described in Additional server-specific configuration.

Running the Test Drive as a J2EE web application

In addition to the BlazeDS WAR file, the BlazeDS download includes a series of web applications fully configured with BlazeDS. There are two test drive applications:

  • Samples
  • Samples-spring

To run the test drive after the install:

Start your application server. # 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). # Open a browser window. # Access one of the sample application home pages by opening the one of the following URLs in a browser (the host name and port number of the deployed war file depends on the configuration of your web application): ** http://hostName:portNumber/samples/ ** http://hostName:portNumber/samples-spring/ # Take the test drive!

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

Tomcat

To use BlazeDS with Tomcat, follow these steps after deploying the BlazeDS WAR files. These steps are not necessary for the integrated (turnkey) Tomcat installation. # 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 # (Optional) To enable custom authentication, locate the Tomcat security resource libraries under install_root/resources/security/tomcat. ## Put flex-tomcat-common.jar in tomcat/lib/blazeds. ## Place flex-tomcat-server.jar in tomcat/lib/blazeds.

  1. 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

  2. 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"> </valve></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. </valve>

  3. You may also need to update the active <login-command> in /WEB-INF/flex/services-config.xml </login-command>

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"> ... # (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. # Restart Tomcat.</login-command></security></security>

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></context-param>

    <param-value>/WEB-INF/activemq.xml</param-value>

    <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:


    <beans>
    <broker usejmx="true" persistent="false" xmlns="http://activemq.org/config/1.0" brokername="myBroker"></broker></beans>

    <transportConnectors>
  <transportconnector name="default" uri="tcp://localhost:61716">
</transportConnectors>
</transportconnector>



    This starts an ActiveMQ message broker with a broker name of myBroker listening for requests on the localhost network interface at port 61716.
    1. 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"></context>

    <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">
</valve></resource></resource></resource></resource>

  8. 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

h5.Running the monitoring application, ds-console.war, on WebSphere with administrative security

  1. Uncomment the <security> section under the RuntimeManagement destination in the services-config.xml file for the ds-console web application. The file contains comments instructing users to do this when running on WebSphere with administrative security enabled.</security>
  2. Uncomment the <security-constraint> section under <security> in the services-config.xml file for the ds-console web application. The file has comments instructing users to do this when running on WebSphere with administrative security enabled.</security></security-constraint>
  3. Make sure that you use the WebSphereLoginCommand.
  4. Create a WAS User Group called console_administrator and add any users who are allowed to use this application to this group. These users must also have at least one role that allows them to access MBeans under WebSphere security.

JBoss

JBoss web application deployment

JBoss deployment requires a web application directory structure to follow a specific naming convention. For example, to deploy the samples web application, you must expand the samples.war file to a directory called samples.war and then copy that to the JBoss deployment directory.

JBoss 4 authentication

(Optional) This configuration provides custom authentication against the current JBoss realm. Usually, the default location 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.

  1. Copy the flex-tomcat-common.jar and flex-tomcat-server.jar files from the install_root/resources/security/tomcat folder to the jboss_root/server/default/lib folder.

  2. Add the TomcatValve to the context.xml in the jboss_root/server/default\deploy/jboss-web.deployer folder:
    <valve classname="flex.messaging.security.TomcatValve"></valve>

  3. Add users and roles to the users.properties and roles.properties files in jboss under jboss_root/server/default/conf folder.

  4. Restart JBoss.

You will now be authenticated against the current JBoss realm.

JBoss 5 authentication

This configuration provides custom authentication against the current JBoss realm:

  1. Copy the flex-tomcat-common.jar and flex-tomcat-server.jar files from the install_root/resources/security/tomcat folder to the jboss_root/server/default/lib folder.

  2. Add the TomcatValve to the context.xml under \server\default\deploy\jboss-web.sar:
    <valve classname="flex.messaging.security.TomcatValve"></valve>

  3. Create a tomcat-users.xml file in the jboss_root/server/default/conf directory. The following example shows a basic tomcat-users.xml file:
    <xml version="1.0" encoding="utf-8" ?=""> <tomcat-users> <role rolename="tomcat"> <role rolename="role1"> <user username="tomcat" password="tomcat" roles="tomcat"> <user username="both" password="tomcat" roles="tomcat,role1"> <user username="role1" password="tomcat" roles="role1"> </user></user></user></role></role></tomcat-users></xml>

  4. Replace the current security realm in the server.xml file under \server\default\deploy\jboss-web.sar with the following:
    <realm classname="org.apache.catalina.realm.MemoryRealm" pathname="../server/default/conf/tomcat-users.xml"></realm>
  5. Restart JBoss.

Running BlazeDS from a compressed WAR file

To run BlazeDS from a compressed WAR file, perform the following steps: # Expand the flex.war file using winzip or the JAR utility. # 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. # Create a compressed WAR file from the expanded web application structure. # 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.

Upgrading BlazeDS 3.2 to version 4.0

BlazeDS 4.0 ships with an empty web application called blazeds.war. You likely used the blazeds.war from version 3.2 as the basis for the web application that you want to upgrade. You are going to use the blazeds.war from version 4.0 as the basis of your upgraded version 3.2 web application.

Note: BlazeDS 4.0 introduced a new empty web application called blazeds-spring.war. Since this is a new application introduced in this release, your upgrade will use the blazeds.war and not include blazeds-spring.war.

The following procedure describes how to upgrade an existing installation of BlazeDS 3.2 to BlazeDS 4.0:

  1. Install BlazeDS 4.0.
  2. Create a backup copy of your existing version 3.2 web application. As part of this procedure, you copy assets from the backup copy to the new BlazeDS 4.0 web application.
  3. Uninstall your existing BlazeDS 3.2 web application from your application server. The steps to do this uninstall are based on your application server. For more information, see the documentation for your application server.
  4. Expand the empty blazeds.war file installed with version 4.0. If you are starting with a packaged blazeds.war, you will need to expand it to a directory and then repackage it when you are finished.

  5. Copy the assets from your existing version 3.2 web application to the empty BlazeDS 4.0 web application. Copy all image, font, SWF, Java, and JAR and other files required by your application.
    Note: Do not copy any configuration files from the WEB-INF/flex directory of your existing version 3 web application.

  6. Merge the configuration files from the WEB-INF/flex directory of your existing version 3.2 web application to the configuration files in the WEB-INF/flex directory of the new BlazeDS 4.0 web application. To perform this merge, copy and paste your destination, channel, endpoint, and other definitions from the version 3.2 configuration files to the version 4.0 configuration files.
    Note: Because configuration files can contain new configuration properties, or change the default values of existing properties, do not overwrite the version 4.0 configuration files with the version 3.2 configuration files. Instead, always merge your custom settings into the version 4.0 configuration files.

  7. (Optional) If you deploy a compressed or packaged web application, repackage the web application.

  8. Deploy the new web application on your application server.

Related

Home: blazeds_gettingstarted