AIR based Tool to generate Flex code for consuming/exposing BlazeDS Remoting services

Thanks for showing interest in BlazeMonster. Please find details at this URL http://sujitreddyg.wordpress.com/blazemonster/

Thank you

Setting up BlazeDS

This article explains how to setup BlazeDS for your J2EE web application.

BlazeDS adds a lot of power to your web applications. You can expose your Java classes as Remoting services. You can use the Messaging service of BlazeDS to expose publish subscribe messaging destinations and also use the Proxy service to invoke other services.

More details about BlazeDS can be found at this URL http://opensource.adobe.com/wiki/display/blazeds/BlazeDS

Updated: Free AIR based Tool to generate Flex code for consuming/exposing Java classes as BlazeDS Remoting services. Visit this URL for more details http://sujitreddyg.wordpress.com/2009/05/07/blazemonster/

Just follow the steps below you will have BlazeDS setup in no time

Getting BlazeDS

Step 1:

Download release build of BlazeDS. BlazeDS release builds are available at this URL http://opensource.adobe.com/wiki/display/blazeds/Release+Builds Click on “Download the BlazeDS binary distribution” to download the binary distribution. Binary distribution has just jar files and other configuration files required.

Step 2:

Go to folder where you saved the downloaded file in Step 1. You would have downloaded a file named blazeds-bin-3.2.0.3978.zip. Extract the content in this file to a folder named blazeds-bin-3.2.0.3978

Step 3:

In the blazeds-bin-3.2.0.3978 folder you will find a file named blazeds.war and blazeds-bin-readme.htm. blazeds-bin-readme.htm contains terms and conditions and license details. blazeds.war contains required jar files and configuration files for setting up BlazeDS.

Extract the content in blazeds.war file into a folder called blazeds. You can extract the content using tools like winzip.

Now we have downloaded and have the required files extracted to setup BlazeDS for a web application. Let’s create a web application.

Creating web application

If you don’t have Tomcat installed, install Tomcat from http://tomcat.apache.org/

Step 4:

In your Tomcat installation directory, you will find a folder named webapps. Usually it is at this location on Windows Operating System “C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps”

Create a web application named samplewebapp. You do this by just creating folder named samplewebapp under webapps folder.

Setting up BlazeDS

We will setup BlazeDS for the web application created in the previous step.

blazeds – this is the folder in which we have blazeds.war content extracted into  in Step 3

samplewebapp – this is the folder created in Step 4

Step 5:

Copy all .jar files from blazeds/WEB-INF/lib to samplewebapp/WEB-INF/lib

Step 6:

Copy blazeds/WEB-INF/flex folder to samplewebapp/WEB-INF

This folder (blazeds/WEB-INF/flex) contains BlazeDS configuration files. Use these files to configure Remoting/Messaging/Proxy services.

Step 7:

Now we will add Servlet mapping for BlazeDS Servlet named MessageBrokerServlet, so that BlazeDS is invoked when you send request for a Remoting/Messaging/Proxy destination using any of the channels supported.

Copy blazeds/WEB-INF/web.xml to samplewebapp/WEB-INF

If you already have a web.xml configured, then you can just copy the Servlet mapping for MessageBrokerServlet and the session listener. You can either copy the content below or copy it from the blazeds/WEB-INF/web.xml

<!-- Http Flex Session attribute and binding listener support -->

<listener>

<listener-class>flex.messaging.HttpFlexSession</listener-class>

</listener>

<!-- MessageBroker Servlet -->

<servlet>

<servlet-name>MessageBrokerServlet</servlet-name>

<display-name>MessageBrokerServlet</display-name>

<servlet-class>flex.messaging.MessageBrokerServlet</servlet-class>

<init-param>

<param-name>services.configuration.file</param-name>

<param-value>/WEB-INF/flex/services-config.xml</param-value>

</init-param>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>MessageBrokerServlet</servlet-name>

<url-pattern>/messagebroker/*</url-pattern>

</servlet-mapping>

That’s it you have BlazeDS setup for your web application.

Now that you have BlazeDS set up you can try invoking Java methods from your Flex applications or create a simple chat application. You can find articles at the URLs below.

http://sujitreddyg.wordpress.com/2008/01/14/invoking-java-methods-from-adobe-flex/

http://sujitreddyg.wordpress.com/2008/01/17/messaging-using-flex-and-blaze-ds/

http://sujitreddyg.wordpress.com/2008/02/12/handling-java-exceptions-in-flex-application/

Adobe Rocks!!!

BlazeDS adapter to invoke multiple classes on a Remoting destination

What is this?

In BlazeDS and LCDS Remoting service, JavaAdapter class allows us to invoke methods on a Java object.  If we want to invoke methods on a Java class, we declare destination for each class we want to be invoked from Flex applications in remoting-config.xml.

I extended the default JavaAdapter and added very very few lines of code so that Flex application can invoke Java classes by specifying the Java class name in the Flex application. Don’t worry, modified adapter allows you to control access to classes using regular expression and other ways.

This will be useful if you have lots of classes, which you want expose as service. Instead of declaring destinations for each class in the remoting-config.xml file, you can use this adapter and expose all required classes by declaring one destination.

What does this adapter let me do?

1.       Specify the name of the Java class in Flex application and invoke methods on that class

2.       You can control access to classes based on regular expression. If you want to allow access to classes in “com.adobe” package only, you can set the source of the destination to “com.adobe.*”.

3.       Declare a default Java class, which will be used if Flex application doesn’t specify the Java class to be used.

4.       From the list of classes allowed in a package, you can exclude few classes

5.       You can specify scope for each class. For example you want instances of 2 classes in the allowed package to be stored in a session or application scope, you can do that.

How to use this adapter?

Adding adapter class to your web application classpath

Download the MultiClassJavaAdapter .java file from this URL http://sujitreddy.g.googlepages.com/MultiClassJavaAdapter.java

Compile it and copy that under WEB-INF/classes folder of your web application in appropriate package structure.

Declaring in remoting-config.xml

The remoting-cong.xml file is explained below. You can download the completed remoting-config.xml file from this URL http://sujitreddy.g.googlepages.com/remoting-config.xml

In the configuration file (remoting-config.xml) file downloaded, you can find we have added our adapter (com.adobe.remoting.adapters.MultiClassJavaAdapter) to the adapters list as shown in the XML snippet below.

<adapters>

<adapter-definition id=”any-java-object” class=”com.adobe.remoting.adapters.MultiClassJavaAdapter”/>

</adapters>

We have destination with id “AnyJavaClass” declared. This destination has its adapter set to the adapter added above using the adapter element.

<destination id=”AnyJavaClass”>

<adapter ref=”any-java-object”/>

</destination>

You can give a regular expression in the configuration file, which will be used to evaluate if a Java class can be invoked by the Flex application on this destination. You will use source property to specify this regular expression as shown below.

You can declare a default Java class, which will be used if the Flex application doesn’t specify the name of the Java class to use. Set the default Java class name using default-source element as shown below.

<destination id=”AnyJavaClass”>

<properties>

<source>com.adobe.*</source>

<default-source>MultiClassAdapterTest</default-source>

</properties>   </destination>

As per declaration above, Flex application can invoke any class under “com/adobe” folder. You might want not want to allow access for few classes in this package. In that case you can declare list of classes you don’t want to exclude as shown below.

<destination id=”AnyJavaClass”>

<properties>

<exclude-classes>

<class name=”com.adobe.ExcludeClass1″/>

<class name=”com.adobe.ExcludeClass2″/>

</exclude-classes>

</properties>    </destination>

By default when there is a request to invoke method on a class, a new instance of that class is created in the request scope. You might want to keep the instances created in application or session scope. Since we are allowing multiple classes to be invoked using single destination, you can declare names of the classes and scope in which you want to store them as shown below.

<destination id=”AnyJavaClass”>

<properties>

<classes-scopes>

<class name=”MultiClassAdapterTest” scope=”session”/>

<class name=”com.adobe.TestClass” scope=”application”/>

</classes-scopes>

</properties>    </destination>

Flex application to test the adapter

Download the MXML file from this URL http://sujitreddy.g.googlepages.com/MultiClassAdapterTesting.mxml

In the file downloaded, you can see that we will use the source property of the RemoteObject class to specify the name of the class to invoke the method on.

That’s it, now you can declare one destination and invoke methods on multiple classes. Still you can control access to classes.

Please feel free to use/edit/delete this class. Any suggestions are most welcome.

Adobe rocks

Creating Factory classes in BlazeDS

What is factory mechanism

BlazeDS provides a factory mechanism that lets you plug in your own component creation and maintenance system to BlazeDS so it integrates with systems like EJB and Spring, which store components in their own namespace.

A factory is responsible for creating the instance that should be used for a request to a destination. When a destination gets a request, destination’s adapter will invoke the configured factory for the destination. When the factory is invoked it should return the instance that should be used by the adapter to process the request.

You can see where exactly a factory is used by the Remoting service at this URL http://sujitreddyg.wordpress.com/2009/01/20/how-remoting-service-in-blazeds-works/

Let’s get into details

Creating a factory

Creating a factory and mapping it to a destination is 3 step process

Create factory class

You just have to create a class which will implement the “flex.messaging.FlexFactory” interface.

Methods to be implemented:

Initialize() – this method will be invoked when the factory class is instantiated. This happens only once.

createFactoryInstance() – this method is invoked for each reference of the factory in a destination. You will get properties declared in the destination as arguments to this method. Every factory class implementing FlexFactory can have a factory instance class extending “flex.messaging.FactoryInstance”. If you have a instance class for your factory create an instance of it and return the same in this method.

Since there is only one instance of the factory class, you can use this factory instance to create instances specific to a destination.

lookUp() – this method is invoked each time there is a request to a destination. If you have a factory instance created and have the lookUp() method overridden in that class, then this will not be invoked. You will receive the instance of the factory instance class returned in the createFactoryInstance() method as argument to this method. You should return the instance of the object that should be used by the adapter.

You can find a sample implementation below.

Create factory instance class

You have to create a class which extends the “flex.messaging.FactoryInstance” class. You should override the constructor. You can override the lookUp() method if you want to do destination based logic in this method. If you don’t override this method, then the lookUp() method in the factory class will be invoked. You should return the instance of the object that should be used by the adapter.

You can find a sample implementation below.

Declaring factory in services-config.xml

To declare a factory class, you should add a tag in the services-config.xml file as shown below. Add the “factories” node under the “service-config” node.

The declaration below is for the sample factory class.

<factories>

<factory id=”MyCustomFactory” class=”com.adobe.factories.MyFactory” />

</factories>

Mapping factory to a destination

In order to set a factory for a destination, you should declare that in the configuration file. In this sample we will change the factory of a Remoting destination. Append the node below in the remoting-config.xml under “service” node.

You can see that we have custom properties in the destination below we will be retrieving those in our factory instance.

<destination id=”CustomFactoryDestination”>

<properties>

<factory>MyCustomFactory</factory>

<source>This is the source</source>

<scope>request</scope>

<mypassedproperty>Sujit Reddy G</mypassedproperty>

</properties>

</destination>

Deploying and testing the factory

Explanation for the samples

We created a factory instance which will get the properties from the configuration file of the destination and then create an instance of “FactoryTesting” class. When we invoke getMe() method on the destination, the method is actually invoked on the instance returned by the factory instance class.

Download the following files

MyFactory.java

MyFactoryInstance.java

FactoryTesting.java

FactoryDestinationTesting.mxml

1.       Copy the .class files of MyFactory.java, MyFactoryInstance.java and FactoryTesting.java files in appropriate folders based on the packages.

2.       Add factory declaration in service-config.xml and declare destination in remoting-config.xml as mentioned above

3.       Create a Flex project pointing to the BlazeDS/LCDS where we have the classes deployed and factory configured.

4.       Use the FactoryDestinationTesting.mxml to invoke and see that the object instance created in the factory instance created is on which the method is invoked.

That’s it Adobe rocks

How Remoting service in BlazeDS works

In this post I tried to explain how Remoting service in BlazeDS works. Obviously I cannot explain each and every line of the code; I tried my best to cover all. I explained how each component of the Remoting service are invoked sequentially to invoke the method on the Java class and return the values.

I took remoting-config.xml file as the starting point to explain how each component is tied.

Recalling how to create Remoting destinations

In order to invoke methods on a Java class, we declare destination for that class in the remoting-config.xml file. From the Flex application we use the RemoteObject and invoke methods on the class by mapping it to the id of the destination declared.

How do they work and who are they?

Remoting Service

<service id=”remoting-service”  class=”flex.messaging.services.RemotingService”>

This will be the root node of the remoting-config.xml. Observe that “class” attribute is set to “flex.messaging.services.RemotingService”. This means the destinations under this “service” node will be handled by the “flex.messaging.services.RemotingService” class.  When a destination gets a request, RemotingService will invoke the appropriate adapter for the destination to get the result.

Adapter

<adapters>

<adapter-definition id=”java-object” class=”flex.messaging.services.remoting.adapters.JavaAdapter” default=”true”/>

</adapters>

This is how we declare adapters for this service. Each destination will have an adapter. You can see that the “default” attribute is set to “true”. This means that if a destination declaration doesn’t specify an adapter, then the default adapter will be used.

In our normal remoting JavaAdapter class is the adapter. JavaAdapter is responsible for invoking method on object and return the result. JavaAdapter also checks if the method invocation is allowed. JavaAdapter will depend on the JavaFactory class to get the object instance on which the method should be invoked.

Factory

<destination id=”my-destination”>

<properties>

<source>flex.samples.EmployeeService </source>

<scope>application</scope>

</properties>

</destination>

This is how we declare a Remoting destination. This destination has its “source” set to “flex.samples.EmployeeService” and “scope” set to “application”.

JavaFactory will use the value of the “source” element to decide which type of object to instantiate and the value of the “scope” element to decide in which scope of the web application the created instance should be stored or look for the instance already created.

JavaFactory is responsible for returning the object instance. In this case JavaFactory is responsible for returning the instance of the “flex.samples.EmployeeService”. If the “scope” is set to application/session then the JavaFactory will check if there is already an instance in the scope and return that. If the object is not available then it is instantiated and stored in appropriate scope.

Wait a second we did not declare a “factory” in the destination. Yes, we did not declare “factory” because JavaFactory is the default factory used by the JavaAdapter.

Complete flow

RemotingService will invoke the JavaAdapter. JavaAdapter will do necessary checks and invoke JavaFactory. JavaFactory will return the instance based on the “source” and “scope” element values. JavaAdapter will now invoke the method on the instance using Java Reflection API and return the result. RemotingService will return the same. MessageBroker will take it from here.

That’s it, each component work so well to allow us to remotely invoke methods on the Java classes.

Measuring message processing performance

Firstly, LiveCycle Data Services 2.6 Developer Guide is amazing. Everything is explained clearly. LCDS team rocks

LiveCycle Data Services developer guide: http://www.adobe.com/go/lcds26_devguide

I was going through the document and found a topic which explains how adding a few tags in the services-config.xml file will get lots and lots of metrics regarding processing time of a message. Information regarding message size, server processing time, and network travel time is available to the clients. You can also get information on the server logs. This works for all types of channels. That means you can also measure performance for a Remoting call also. This is available in both BlazeDS and LCDS

You can find detailed explanation on this mechanism at this URL:

http://livedocs.adobe.com/livecycle/8.2/programLC/programmer/lcds/mpi_1.html

Few metrics I liked the most are message size, server adapter time, server processing time, server send time and total time. There are lot more, you can find a table explaining the metrics in the URL included above.

We will have a look at main steps required to enable gathering metrics with a Remoting sample.

On the server

First you need to tell your channel to send the metrics to the clients. For this you need to add 2 tags in services-config.xml under the channel tag as shown below. Here I am adding it for an AMF channel. I am using this channel for my Remoting Service destinations. In the code snippet below tags in bold are the ones to be added. You have to add the tags for the channel you want the metrics for.

<channels>

<channel-definition id=”my-amf” class=”mx.messaging.channels.AMFChannel”>

<endpoint url=”http://{server.name}:{server.port}/{context.root}/messagebroker/amf” class=”flex.messaging.endpoints.AMFEndpoint”/>

<properties>

<serialization><instantiate-types>false</instantiate-types></serialization>

<polling-enabled>false</polling-enabled>

<record-message-times>true</record-message-times>

<record-message-sizes>true</record-message-sizes>

</properties>

</channel-definition>

</channels>

On the client

MessagePerformanceUtils class will help you to parse the metrics from the message returned from the server. All you need to do is to pass the message to the MessagePerformanceUtils class constructor in the result handler. Once this is done, you will use MessagePerformanceUtils instance to retrieve the metrics.

Please download sample from this URL:

http://sujitreddy.g.googlepages.com/PerformanceMeasuringSample.mxml

In the function below which is the result handler in the sample code attached, you can see we are passing the message object returned by the server to the MessagePerformanceUtils class. prettyPrint() method of this class returns a formatted string of metrics. You can find more details on MessagePerformanceUtils class at this URL http://livedocs.adobe.com/flex/3/langref/mx/messaging/messages/MessagePerformanceUtils.html

private function handleServerResponse(event:ResultEvent):void{

remoteObject.removeEventListener(ResultEvent.RESULT, handleServerResponse);

remoteObject.removeEventListener(FaultEvent.FAULT,               handleServerFault);

//processing the result

var performanceDetails:MessagePerformanceUtils =

new MessagePerformanceUtils(event.message);

txtOutput.text = performanceDetails.prettyPrint();

}

Creating Remoting destination and Java class

Please find details on how to invoke Java methods from Flex using Remoting at this URL

http://sujitreddyg.wordpress.com/2008/01/14/invoking-java-methods-from-adobe-flex/

All you need to do is to create a Remoting destination with TestingOnly as id and set the source to a Java class with method below.

public String echo(String echoString){return echoString;}

That’s all you need to do now you have all metrics required to measure message processing performance.

Adobe Flash Platform it is

Adobe Flash Platform

Innovation that stands out, technology that fits in

Image from http://www.adobe.com/flashplatform/

Excellent branding … Great going Adobe !

Securing BlazeDS destinations using custom Tomcat REALM authentication

I was planning to write a post on how to secure BlazeDS/LCDS destination using custom REALM authentication in Tomcat. Before wrting, I searched for articles on this topic and found good articles on how to do the same. I thought of including the URLs to those articles instead of writing a new article.

You can find details on how to create a custom authentication class for Tomcat at this URL

http://lekkimworld.com/2005/07/29/1122648646441.html

BlazeDS developer guide has a awesome article with sample on how to secure your destinations based on Tomcat Realm authentication. Please find article at this URL

Configuration: http://livedocs.adobe.com/blazeds/1/blazeds_devguide/services_security_3.html

Basic authentication: http://livedocs.adobe.com/blazeds/1/blazeds_devguide/services_security_4.html

Custom authentication: http://livedocs.adobe.com/blazeds/1/blazeds_devguide/services_security_5.html

Secure your destinations

Sending messages from Java to BlazeDS destinations using MessageBroker

We discussed BlazeDS/LCDS messaging samples in which we produce messages from a Flex application and consume that message from another or same Flex application. BlazeDS/LCDS also allows us to publish messages to messaging destinations from a Java class on the server.

As BlazeDS/LCDS allows us to publish messages from a Java class on server, we can build a JSP/Servlet which will invoke this Java class and publish messages to BlazeDS/LCDS messaging destination. We can establish messaging between and Flex and Non-Flex client.

I created a simple sample in which I am sending messages from a JSP page to a Flex client. This is so simple. All you need to do is to create a Java class with one method in it and a JSP which will invoke this Java class. You will also create Flex application which will subscribe to the destination to which we will publish messages from our Java class.

Let’s start coding:)

First we will create the Java class which will publish the message.

MessageSender.java

We have only one method in this class called sendMessageToClients. In this method we will create a message of the type AsyncMessage and publish that message using MessageBroker. AsyncMessage and MessageBroker class are available with BlazeDS in the flex-messaging-core.jar. You should be adding this jar to your project libraries to compile this class. Download the Java file compile it and deploy it in WEB-INF/classes folder of your web application.

Download this Java file from this URL: http://sujitreddy.g.googlepages.com/MessageSender.java

public void sendMessageToClients(String messageBody)

{

AsyncMessage msg = new AsyncMessage();

msg.setClientId(“Java-Based-Producer-For-Messaging”);

msg.setTimestamp(new Date().getTime());

//you can create a unique id

msg.setMessageId(“Java-Based-Producer-For-Messaging-ID”);

//destination to which the message is to be sent

msg.setDestination(“TestingDestination”);

//set message body

msg.setBody(messageBody != null?messageBody:”");

//set message header

msg.setHeader(“sender”, “From the server”);

//send message to destination

MessageBroker.getMessageBroker(null).routeMessageToService(msg, null);

}

sendmessage.jsp

Download the JSP from this URL: http://sujitreddy.g.googlepages.com/sendmessage.jsp

In this JSP file we will just invoke the Java class created above.

MessageFromServerSample.mxml

In this MXML file we will be subscribing to the destination and also act as a producer for the same destination. You can find more details on messaging in Flex at this URL http://sujitreddyg.wordpress.com/2008/01/17/messaging-using-flex-and-blaze-ds/

Download this MXML file from this URL: http://sujitreddy.g.googlepages.com/MessageFromServerSample.mxml

messaging-config.xml

This is file in which we will configure our destination to which we are publishing messages and subscribing to get messages.  Just add the XML tag below as a child to <service> tag in messaging-config.xml file in your BlazeDS configured web application under Web-INF/flex folder. Please make sure you have default channel set in the messaging-config.xml.

<destination id=”TestingDestination”>

</destination>

That is all you need to do. Run the Flex application and then try some text and see if you are receiving the messages as the Flex application is acting as both producer and consumer for the same destination. If you are receiving the messages send by you, which means the messaging destination is configured properly. Now just launch the sendmessage.jsp page from the browser, you should be able to see the message sent from the Java class in the Flex client.

That’s it:) Adobe Rocks

Session data management in Flex Remoting

If you are using Flex Remoting to communicate with Java classes on the server, you might want to maintain instance of an object across a user session. For example you might want to store the User object after successful authentication of a user. BlazeDS provides class named FlexContext.

Please visit the BlazeDS Developer guide at this URL for more details on FlexContext class and session data management. BlazeDS Developer Guide

Updated: Free AIR based Tool to generate Flex code for consuming/exposing Java classes as BlazeDS Remoting services. Visit this URL for more details http://sujitreddyg.wordpress.com/2009/05/07/blazemonster/

I created a simple Java class which will add objects to session. It will also retrieve objects from session and modify them. I access this Java class from a Flex application to get the data which is stored in user session. In this sample we will be creating one Java class and one .mxml file.

Pre-requisite: Knowledge on how to invoke Java methods from Flex applications and also have BlazeDS set up on your server. If you have not done this, please visit this URL for details on how to access Java methods from Flex applications. Invoking Java methods from Flex applications

Let’s move into details. First create a Java class as shown below.

com.adobe.services.MySessionHandler.java

Download this file from this URL: MySessionHandler.java

In the constructor I am checking if object already exists in the session and add objects if necessary. We have two objects in the session. One is userName which is object of type java.lang.String and myCounter which is object of type java.lang.Integer and is used to store a counter. We will provide method to increment this counter.

public MySessionHandler()

{

mySession= FlexContext.getFlexSession();

if(mySession.getAttribute(“myCounter”) == null)

{

mySession.setAttribute(“myCounter”, new Integer(1));

}

if(mySession.getAttribute(“userName”) == null)

{

mySession.setAttribute(“userName”, “Sujit Reddy G”);

}

}

In this method we are incrementing the value of the object stored in the session.

public void increaseCounter()

{

Integer i = (Integer) mySession.getAttribute(“myCounter”);

i = i + 1;

mySession.setAttribute(“myCounter”, i);

}

You can find more methods in Java file attached. Download the file and place the compiled file into WEB-INF/classes folder of the web application where your BlazeDS is present. You should add flex-messaging-core.jar to your project build path in Eclipse to compile this class.

You should add a destination to your remoting-config.xml. I have added the following under the service tag in my remoting-config.xml.

<destination id=”MySessionHandler” channels=”my-amf”>

<properties>

<source>com.adobe.services.MySessionHandler</source>

</properties>

<adapter ref=”java-object”/>

</destination>

SessionSample.mxml

Download this file from this URL: SessionSample.mxml

In this Flex application we have three buttons which will invoke methods on the Java class created above to get the results. There are three methods which we will invoke.

getUserName() – this will return the user name stored in the session

getCounter() – this will return the value of the counter

increaseCounter() – this will increment the counter value

You have to map your Flex application to the web application with BlazeDS as described in the pre-requisite for this blog.

That is all you need to do. It’s that easy to manage session data while using Flex Remoting.