Quick start with GraniteDS

By William December 2nd, 2011 Flex, GraniteDS 14 Comments

---

You have now two very easy ways to quickly create a new GraniteDS project – or to get quickly started with the platform if you are not familiar with it: a dedicated Eclipse wizard and four Maven archetypes. Both allow to create fully functional projects with only few clicks or command-line options, resulting in pre-configured, ready to deploy, skeleton applications with most of the major features you would use in a real-world project: Flash Builder configuration, Ant build file, JavaEE framework and JPA provider integration, code generation setup, real-time messaging configuration, etc.

If you are a Maven user, you can start with the archetypes that work with embedded servers ( Jetty or Embedded GlassFish), see this paragraph below. Using the wizard can however be helpful in defining proper configurations for other target application servers and environments such as Tomcat or JBoss.

Using the Eclipse Wizard

First, you need to install the GraniteDS wizard and builder plugins in Eclipse. From Eclipse, you can use the Eclipse Marketplace dialog (search for “GraniteDS�?) or add the GraniteDS update site () to the list of available software sites:

You will need to install both the GraniteDS Builder and the GraniteDS Wizard plugins. It will register a GraniteDS / GraniteDS Project wizard with three default templates:

• The Pojo template is a simple template that creates a project configured for basic remoting to a Java service.
• The Chat template is a simple template that creates a project configured for basic client-to-client messaging with a default chat application.
• The Spring/EJB/Seam/CDI template is a bit more advanced and allows to create a project configured with a complete Flex, Java and GraniteDS technology stack, including popular Java frameworks such as Spring and EJB3, JPA support and real-time data push.

The three templates generate a combined Flex/Java project that can be easily converted to an Eclipse WTP project and deployed to a local or remote application server. If you use Flash Builder, the necessary configuration files can be optionally generated so the project can be immediately compiled in Flash Builder. Finally a minimal ant build file will be produced so you can build the project manually if needed.

Let’s see how this works in a few steps:

First select the menu File / New / Other.. (or just type Ctrl+N) then lookup the GraniteDS section and select GraniteDS Project.

Select a template, for example the last one and click Next.

Choose a name for your project, choose your preferred technologies, for example choose Spring 3, Tomcat 7 and Hibernate. Fill up the other information, in particular your Flex SDK home directory (it should be ideally a Flex 4.5 SDK) and the deployment folder of the application server (for example something like /home/dev/apache-tomcat-7.0.22/webapps for Tomcat 7). Keep default values for the others, check Flash Builder and Ant+Ivy build options and click on Finish.

The creation of the new project in the workspace can take some time because the wizard will fetch all necessary libraries on the central Maven repository. If you are using Flash Builder 4.5, you may get the following warning because the generated configuration files are targeted at Flash Builder 4, so just select Flex SDK 4.5+.

With Flash Builder, you will always have an error about HTML wrapper files after the project is built (this is a known Flash Builder issue). Just right click on the error message as suggested and select Recreate HTML templates.

If you don’t use Flash Builder, you can simply use the target build.flex of the generated build.xml ant file that will run the compilation of the Flex application.

At this point, you already have a working project, fully configured for the technologies and server you have chosen in the wizard page. You have now two options to deploy it to your server: run the deploy.war target of the generated ant build.xml file or use Eclipse WTP.

In order to use WTP, you first have to convert the project to a faceted project by right clicking on the project and selecting the menu Configure / Convert to Faceted Form…

On the next page, select Dynamic Web Project with the correct version (3.0 for Tomcat 7 or JBoss 6/7, 2.5 for Tomcat 6 or JBoss 4/5) and select a corresponding server runtime.

Finally, right click on the project and select Debug / Debug on Server…

On the last screen, just check that the correct server is selected (here it should be Tomcat 7) and click on Finish.

Eclipse will start the application server and open a Web browser on the application welcome page. You should get something like this:

You can log in with admin:admin or user:user, and try to enter a few names. If you open a second browser (and not only another tab or window of the same browser!) and point it to the same page (), you should see your modifications reflected in real-time in both browsers.

If you setup automatic publishing in Eclipse WTP (that should be the case by default), any change you make on the Flex application will be automatically deployed on the server. You can simply refresh the page to check your changes once compiled, no need to redeploy anything to develop your UI!

Using the Maven archetypes

If you are a Maven user, it’s likely that you will prefer to start with an archetype. There are four existing GraniteDS archetypes available on the Maven central repository:

archetypeGroupId: org.graniteds.archetypes archetypeVersion: 1.1.0.GA archetypeArtifactId:

• graniteds-spring-jpa-hibernate: Flex 4.5 + Spring 3 + Hibernate 3.6 + GraniteDS 2.3 with standard RemoteObject API
• graniteds-tide-spring-jpa-hibernate: Flex 4.5 + Spring 3 + Hibernate 3.6 + GraniteDS 2.3 with Tide API
• graniteds-tide-seam-jpa-hibernate: Flex 4.5 + Seam 2.2 + Hibernate 3.6 + GraniteDS 2.3 with Tide API
• graniteds-tide-cdi-jpa: Flex 4.5 + CDI/Weld 1.1 + JPA 2.0 + GraniteDS 2.3 with Tide API

The Tide archetypes are equivalent to what you get with the Spring/EJB/Seam/CDI template of the Eclipse Wizard we have seen if the first paragraph. The main differences are that you don’t need to have a Flex SDK installed as it will be retrieved from the Maven repository and that you get 3 separate projects: a Java project, a Flex project and a Webapp project.

Let’s reproduce what we did with the Eclipse Wizard, first with a command line (Maven 3.x required):

mvn archetype:generate
    -DarchetypeGroupId=org.graniteds.archetypes
    -DarchetypeArtifactId=graniteds-tide-spring-jpa-hibernate
    -DarchetypeVersion=1.1.0.GA
    -DgroupId=org.example
    -DartifactId=springgds
    -Dversion=1.0-SNAPSHOT

Once the archetype is created, you can build the project with:

cd springgds
mvn clean package

And finally run the embedded jetty server with:

cd webapp
mvn jetty:run-war

You can now browse  and check that the application works.

The CDI archetype requires a Java EE 6 server and uses an embedded GlassFish that you can run with:

cd webapp
mvn embedded-glassfish:run

With the Eclipse Maven integration (the M2E plugin), you can simply choose one of the archetypes when doing New Maven Project.

To deploy the application to a real server, you can use the following goal to build a war file:

mvn war:war

Note however that when doing this you may have to change the configuration of the application. In general you have to change the name of the Gravity servlet in web.xml and most likely update your JPA configuration. You can use the Eclipse Wizard to generate a configuration corresponding to your case.

Conclusion

It now takes literally 5 minutes (and less than 1 minute after the first run) to start a new Flex / Java project with GraniteDS. You no longer have any excuse not to try it!

Tags: tutorial