GraniteDS Documentation

You need at least the following four free development tools:

This section will guide you through the setting up of a very basic GraniteDS project deployed in Tomcat and a Java command line client. Expected result is a typical "Hello, world" application.

The client program will pass its argument to the remote service and display the result which should be a string:

"Hello " + <argument> + "!"

        

In order to create, build, and deploy this sample application you need these free tools:

Creation of the project in Eclipse:

Start Eclipse and create a new Java project named helloworld. You may just type in helloworld for Project name and accept all other default settings.

We are now going to create a new POJO service named HelloWorldService. Right-click on the java source folder and select New / Class, enter org.test for Package and HelloWorldService for Name in the following dialog, and then click on the Finish button. In the Java source file editor, modify the code so it is just as follows:

package org.test;


public class HelloWorldService {


    public String sayHello(String name) {

        return "Hello " + name + "!";

    }

}

        

Next we have to create the GraniteDS configuration file services-config.xml and the web application web.xml at the root of the project.

Copy and paste the following code into these files:

<?xml version="1.0" encoding="UTF-8"?>

<services-config>



    <services>

        <service

            id="granite-service"

            class="flex.messaging.services.RemotingService"

            messageTypes="flex.messaging.messages.RemotingMessage">

            <destination id="helloWorldService">

                <properties>

                    <scope>application</scope>

                    <source>org.test.HelloWorldService</source>

                </properties>

            </destination>

        </service>

    </services>

</services-config>

        

<?xml version="1.0" encoding="UTF-8"?>

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/j2ee"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee

                        http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd">



    <!-- general information about this web application -->

    <display-name>Hello World</display-name>

    <description>Hello World Sample Application</description>



    <!-- read services-config.xml file at web application startup -->

    <listener>

        <listener-class>org.granite.config.GraniteConfigListener</listener-class>

    </listener>



    <!-- handle AMF requests ([de]serialization) -->

    <filter>

        <filter-name>AMFMessageFilter</filter-name>

        <filter-class>org.granite.messaging.webapp.AMFMessageFilter</filter-class>

    </filter>

    <filter-mapping>

        <filter-name>AMFMessageFilter</filter-name>

        <url-pattern>/graniteamf/*</url-pattern>

    </filter-mapping>



    <!-- handle AMF requests (execution) -->

    <servlet>

        <servlet-name>AMFMessageServlet</servlet-name>

        <servlet-class>org.granite.messaging.webapp.AMFMessageServlet</servlet-class>

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

    </servlet>

    <servlet-mapping>

        <servlet-name>AMFMessageServlet</servlet-name>

        <url-pattern>/graniteamf/*</url-pattern>

    </servlet-mapping>



</web-app>

        

Next we have to build and deploy the server application:

Create a folder named lib at the root of the project and put granite.jar in this folder. Create a new file named build.xml at the root of the project and copy/paste the following content into it; you may have to modify TOMCAT_HOME to reflect your environment:

<?xml version="1.0" encoding="UTF-8"?>

<project name="hello-world" default="deploy">



    <!-- Modify TOMCAT_HOME properties to reflect your environment -->

    <property name="TOMCAT_HOME" value="/apache-tomcat-7.0.29"/>

    

    <!-- Build a war suitable for Tomcat (and other) -->

    <target name="war">

        <mkdir dir="build"/>

        <war destfile="build/helloworld.war" webxml="web.xml">

            <zipfileset file="services-config.xml" prefix="WEB-INF/flex" />

            <lib dir="lib"/>

            <classes dir="bin"/>

        </war>

    </target>



    <!-- Deploy the war in Tomcat -->

    <target name="deploy" depends="war">

        <copy todir="${TOMCAT_HOME}/webapps" file="build/helloworld.war"/>

    </target>



</project>

        

You may now right-click on the build.xml file and select Run As / Ant Build. This will launch the build process, create a WAR (Web Archive), and copy it into your Tomcat webapps directory.

Then start Tomcat. Go to the directory bin just under your Tomcat installation directory, /apache-tomcat-7.0.29/bin for example, and double-click on startup.bat, or startup.sh for Unix/Mac users. After a short while, you should see in the console that Tomcat has started.

You should now see something like the following picture under Eclipse:

Now let create the Java client code, for this example we are simply going to create a command line application but we could use any Java view technology, such as Swing, JavaFX or SWT.

Create a new Java project named helloworld-client. Create a new class directly in this new folder and name it HelloWorldClient in the package org.test.client by right-clicking on the src folder and selecting New / Class. In the editor, type in the following code:

package org.test.client;


import java.net.URI;

import java.util.concurrent.TimeUnit;


import org.granite.client.messaging.RemoteService;

import org.granite.client.messaging.ResultFaultIssuesResponseListener;

import org.granite.client.messaging.channel.amf.AMFRemotingChannel;

import org.granite.client.messaging.events.FaultEvent;

import org.granite.client.messaging.events.IssueEvent;

import org.granite.client.messaging.events.ResultEvent;

import org.granite.client.messaging.transport.apache.ApacheAsyncTransport;


public class HelloWorldClient {


    public static void main(String[] args) throws Exception {

        ApacheAsyncTransport transport = new ApacheAsyncTransport();

        transport.start();

        AMFRemotingChannel channel = new AMFRemotingChannel(transport, 

            "graniteamf", new URI("http://localhost:8080/helloworld/graniteamf/amf.txt"));      

        RemoteService service = new RemoteService(channel, "helloWorldService");

        service.newInvocation("sayHello", args[0]).setTimeToLive(5, TimeUnit.SECONDS)

            .addListener(new ResultFaultIssuesResponseListener() {

            

            @Override

            public void onResult(ResultEvent event) {

                System.out.println("Result: " + event.getResult());

            }

            

            @Override

            public void onFault(FaultEvent event) {

                System.err.println("Fault: " + event.toString());

            }

            

            @Override

            public void onIssue(IssueEvent event) {

                System.err.println("Issue: " + event.toString());

            }

        }).invoke();

    }

}

        

You will also need to add a few libraries in a lib folder and add them to the build path of the project with Right Click/Build Path/Add to Builder Path:

You may now run the Java application in Eclipse by right-clicking the class HelloWorldClient and Run As.../Java Application. The result should appear in the Eclipse console. You can test different results by changing the run arguments in the Eclipse Run configuration for the application.

Here are some highlights on some parts of the code and configuration:

public String HelloWorldService.sayHello(String name)

        

The HelloWorldService is a simple Java service which declares a method sayHello() that takes a String argument and returns another String.

<destination id="helloWorldService">

    <channel ref="my-graniteamf"/>

    <scope>application</scope>

    <source>org.test.HelloWorldService</source>

</destination>

        

This part of the services-config.xml defines a mapping between a destination name and the service class and its scope. This is a basic declaration for an application scoped bean that will be created by GraniteDS itself but there are other kinds of configurations that give access to beans managed by an existing container such as Spring, or that use annotations to declare the remoting-enabled classes.

<url-pattern>/graniteamf/*</url-pattern>

        

This part of web.xml defines the mapping between the target url and the GraniteDS servlet. Other kinds of configuration are also possible which use a Spring MVC dispatcher servlet or use Servlet 3 features to automatically initialize the GraniteDS servlet. /graniteamf/* is the default and recommended url mapping for GraniteDS, but any other can work.

ApacheAsyncTransport transport = new ApacheAsyncTransport();

transport.start();

AMFRemotingChannel channel = new AMFRemotingChannel(transport, "my-graniteamf", 

    new URI("http://localhost:8080/helloworld/graniteamf/amf.txt"));

RemoteService srv = new RemoteService(channel, "helloWorldService");

        

This is the initialization part of the GraniteDS Java client. It requires creating a transport (here the default transport based on the Apache asynchronous HTTP client), a remoting channel and a RemoteService whose target destination matches the destination we declared earlier in the server configuration.

srv.newInvocation("sayHello", args[0]).setTimeToLive(5, TimeUnit.SECONDS)

    .addListener(new ResultFaultIssuesResponseListener() {

                

    @Override

    public void onResult(ResultEvent event) {

        System.out.println("Result: " + event.getResult());

    }

    

    @Override

    public void onFault(FaultEvent event) {

        System.err.println("Fault: " + event.toString());

    }

    

    @Override

    public void onIssue(IssueEvent event) {

        System.err.println("Issue: " + event.toString());

    }

}).invoke();

        

This is the main client part where the RemoteService triggers a server request that will call the sayHello() method with the first argument of the main method: srv.sayHello(args[0]).

The result of this call will be displayed, when available, in the console output in the asynchronous result handler of the remote call.

There are two main use cases for the GraniteDS Java client. The first is to help testing of GraniteDS-enabled services outside of a Flex environment, the other is for building rich client applications with any Java view technology (Swing, SWT, JavaFX).

Note that the GraniteDS client library provides extensive support for most advanced features of JavaFX 2.1+.

There are also two main choices for the client/server API:

The Tide remoting API and data management framework include a very minimalistic client application framework (event bus, component container...) and may be integrated with more robust frameworks such a Spring. There is a built-in Spring client integration, and a SPI can be implemented to integrate with other frameworks (Java client support for CDI may be added later).

On the server there are mostly two options :

This section describes some classic technology stacks used with Java applications and GraniteDS.

Spring/Hibernate on Tomcat 6+ or Jetty 6+

This is one of the most common use cases and allows for easy development and deployment. You can furthermore benefit from the extensive support for serialization of Java objects and JPA detached objects, and of NIO/APR asynchronous support of Tomcat 6.0.18+ or Jetty 6 continuations.

EJB3/Hibernate on JBoss 4/5

This is another common use case and it provides roughly the same features than Spring/JPA. The main difference is that it requires a full EE container supporting EJB 3.

Tide/Spring/Hibernate on Tomcat 6+ or Jetty 6+

This is an extension of the first case, with the additional use of the Tide remoting and data management API on the client. This will enable the most advanced features such as data paging, transparent lazy-loading of collections, real-time data synchronization... Tide also provides advanced client-side support for Spring Security authorization that for example allow to easily hide/disable buttons for unauthorized actions. This is currently the most popular technology stack.

Tide/EJB3/Hibernate on JBoss 4/5 or Tide/EJB3/EclipseLink on GlassFish v3

It's also similar to the previous case, but using EJB 3 instead of Spring.

Tide/CDI/JPA2/Java EE 6 on JBoss 6/7 or GlassFish 3

Well this is not really a "common" stack but at least it is a fully Java EE standard6. If you are on a Java EE 6 compliant application server and can live without Spring, it is definitely the best option.

The GraniteDS jars are available from the build folder of the distribution. You will always need granite.jar. Additionally you will have to include the jar corresponding to your server framework (granite-spring.jar for Spring for example), the jar for your JPA provider (granite-hibernate.jar for Hibernate) and the granite-beanvalidation.jar if you want to benefit from the integration with the Bean Validation API on the server.

At the most basic level, GraniteDS is implemented as a servlet (in fact a servlet and a filter) and thus has to be configured in web.xml. Here is a typical code snippet that maps the GraniteDS AMF servlet to /graniteamf/*. Of course it's possible to define a different URL mapping if required. It is also highly recommended to also add the configuration listener that will release resources on application undeployment.

<listener>

    <listener-class>org.granite.config.GraniteConfigListener</listener-class>

</listener>



<filter>

    <filter-name>AMFMessageFilter</filter-name>

    <filter-class>org.granite.messaging.webapp.AMFMessageFilter</filter-class>

</filter>

<filter-mapping>

    <filter-name>AMFMessageFilter</filter-name>

    <url-pattern>/graniteamf/*</url-pattern>

</filter-mapping>



<servlet>

    <servlet-name>AMFMessageServlet</servlet-name>

    <servlet-class>org.granite.messaging.webapp.AMFMessageServlet</servlet-class>

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

</servlet>

<servlet-mapping>

    <servlet-name>AMFMessageServlet</servlet-name>

    <url-pattern>/graniteamf/*</url-pattern>

</servlet-mapping>

        

The configuration of the various GraniteDS parts is done in the file WEB-INF/granite/granite-config.xml. There are many options that can be defined here, you can refer to the configuration reference.

As a starting point, you can create an empty file :

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE granite-config PUBLIC "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/3.0.0/granite-config.dtd">



<granite-config/>

        

Or much easier a configuration that will use class scanning to determine the default setup.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE granite-config PUBLIC "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/3.0.0/granite-config.dtd">



<granite-config scan="true"/>

        

The last thing to define on the server is the application configuration in WEB-INF/flex/services-config.xml. This is for example the place where you will define which elements of your application you will expose to GraniteDS remoting, or the topic for messaging. You can refer to the configuration reference for more details.

For example a simple configuration for an EJB 3 service would look like :

<services-config>

    <services>

        <service id="granite-service"

            class="flex.messaging.services.RemotingService"

            messageTypes="flex.messaging.messages.RemotingMessage">



            <destination id="example">

                <channels>

                    <channel ref="graniteamf"/>

                </channels>

                <properties>

                    <factory>ejbFactory</factory>

                </properties>

            </destination>

        </service>

    </services>



    <factories>

        <factory id="ejbFactory" class="org.granite.messaging.service.EjbServiceFactory">

            <properties>

                <lookup>myapp/{capitalized.destination.id}ServiceBean/local</lookup>

            </properties>

        </factory>

    </factories>



    <channels>

        <channel-definition id="graniteamf" class="mx.messaging.channels.AMFChannel">

            <endpoint

                uri="http://{server.name}:{server.port}/{context.root}/graniteamf/amf"

                class="flex.messaging.endpoints.AMFEndpoint"/>

        </channel-definition>

    </channels>

</services-config>

        

This configuration file declares 3 differents things, let's list them in the reverse order :

Depending on the kind of framework integration that is used, the services-config.xml file may not be necessary and can be omitted. With Spring and Seam for example, everything can be defined in the respective framework configuration files instead of services-config.xml.

GraniteDS comes with 3 client jar libraries. First granite-client.jar, a stripped down version of the core granite.jar that includes the minimal core of GraniteDS. Then granite-java-client.jar that includes the Java client library, and finally granite-javafx-client.jar that contains the specific integration for JavaFX.

The GraniteDS client also depends on the small class scanning library extcos. For remoting and Comet, the GraniteDS client requires the Apache Asynchronous HTTP client, and for WebSocket, the Jetty WebSocket client. All these jars can be found in the libs folder of the Java client distribution.

You simply have to add the necessary GraniteDS jars and dependencies to your application classpath.

Maven is a popular build tool. Though GraniteDS is not itself built with Maven, its artifacts are available in the Maven central repository and can thus be easily added as dependencies to any Maven project.

The Java dependencies for the server application are in the group org.graniteds.

<dependency>

    <groupId>org.graniteds</groupId>

    <artifactId>granite-core</artifactId>

    <version>${graniteds.version}</version>

    <type>jar</type>

</dependency>



<dependency>

    <groupId>org.graniteds</groupId>

    <artifactId>granite-hibernate</artifactId>

    <version>${graniteds.version}</version>

    <type>jar</type>

</dependency>



...

        

The dependencies for the Java client application are as follows:

<dependency>

    <groupId>org.graniteds</groupId>

    <artifactId>granite-client</artifactId>

    <version>${graniteds.version}</version>

    <type>jar</type>

</dependency>



<dependency>

    <groupId>org.graniteds</groupId>

    <artifactId>granite-java-client</artifactId>

    <version>${graniteds.version}</version>

    <type>jar</type>

</dependency>



<!-- Only for JavaFX integration -->

<dependency>

    <groupId>org.graniteds</groupId>

    <artifactId>granite-javafx-client</artifactId>

    <version>${graniteds.version}</version>

    <type>jar</type>

</dependency>



<!-- Default dependencies -->

<dependency>

    <groupId>net.sf.extcos</groupId>

    <artifactId>extcos</artifactId>

    <version>0.3b</version>

    <type>jar</type>

</dependency>



<!-- Apache HTTP client dependencies (remoting, Comet) -->

<dependency>

    <groupId>org.apache.httpcomponents</groupId>

    <artifactId>httpasyncclient</artifactId>

    <version>4.0-beta1</version>

    <type>jar</type>

</dependency>



<!-- Jetty WebSocket client dependencies (WebSocket) -->

<dependency>

    <groupId>org.eclipse.jetty</groupId>

    <artifactId>jetty-client</artifactId>

    <version>8.1.5.v20120716</version>

    <type>jar</type>

</dependency>

<dependency>

    <groupId>org.eclipse.jetty</groupId>

    <artifactId>jetty-websocket</artifactId>

    <version>8.1.5.v20120716</version>

    <type>jar</type>

</dependency>



        

The Tide remoting API is an alternative to the low-level RemoteService API that simplifies the handling of asynchronicity and brings much more features that will be described in the next chapters.

public class HelloExample {


    public static void main(String[] args) {

    

        ContextManager contextManager = new SimpleContextManager(new DefaultPlatform());

        Context context = contextManager.getContext();

        

        ServerSession serverSession = new ServerSession("spring", "/myapp", "localhost", 8080);

        context.set(serverSession);

        serverSession.start();

        

        Component helloService = new ComponentImpl(serverSession);

        context.set("helloService", helloService);

        

        // Asynchronous call using handlers

        helloService.call("sayHello", "Barack", new TideResponder<String>() {

            @Override

            public void result(TideResultEvent<String> result) {

                System.out.println("Async result: " + result.getResult());

            }

            

            @Override

            public void fault(TideFaultEvent fault) {

                System.err.println("Fault: " + fault.getFault());

            }

        };

        

        // Synchronous wait of Future result

        Future<String> futureResult = helloService.call("sayHello", "Barack");

        String result = futureResult.get();

        System.out.println("Sync result: " + result);

    }

            

package com.myapp.client;


@Configuration

public class Config {

    

    @Bean

    public SpringEventBus eventBus() {

        return new SpringEventBus();

    }

    

    @Bean

    public SpringContextManager contextManager(SpringEventBus eventBus) {

        return new SpringContextManager(new JavaFXPlatform(eventBus));

    }

    

    @Bean(initMethod="start", destroyMethod="stop")

    public ServerSession serverSession() throws Exception {

        return new ServerSession("spring", "/test", "localhost", 8080);

    }

    

    @Bean

    public Component helloService(ServerSession serverSession) {

        return new ComponentImpl(serverSession);

    }

    

    @Bean(initMethod="start")

    public App app() {

        return new App();

    }

}

            

package com.myapp.client;


public class App {


    public static void main(String[] args) {

        ApplicationContext applicationContext = new AnnotationConfigApplicationContext();

        applicationContext.scan("com.myapp.client");

        applicationContext.refresh();

        applicationContext.registerShutdownHook();

        applicationContext.start();

    }

    

    @Inject @Qualifier("helloService")

    private Component helloService;

    

    public void start() {

        helloService.call("sayHello", "Barack", new TideResponder<String>() {

            @Override

            public void result(TideResultEvent<String> result) {

                System.out.println("Async result: " + result.getResult());

            }

            

            @Override

            public void fault(TideFaultEvent fault) {

                System.err.println("Fault: " + fault.getFault());

            }

        };

    }

}

            

public static class HelloResponder implements TideResponder {


    private final String token;


    public HelloResponder(String token) {

        this.token = token;

    }

    

    @Override

    public void result(TideResultEvent event) {

        System.out.println("Result for " + token + ": " + event.getResult());

    }

    

    @Override

    public void fault(TideFaultEvent event) {

        System.err.println("Fault for " + token + ": " + event.getFault());

    }

}


public void call() {

    helloService.call("sayHello", "Barack", new HelloResponder("firstCall"));

    helloService.call("sayHello", "Barack", new HelloResponder("secondCall"));

}

            

private List<Product> products = new ArrayList<Product>();


public function call():void {

    productService.findAllProducts(new TideMergeResponder<List<Product>>() {

        @Override

        public void result(TideResultEvent<List<Product>> event) {

            System.out.println("Result was merged: " + (event.getResult() == products));

        }

        

        @Override

        public void fault(TideFaultEvent event) {

            System.err.println("Fault for " + token + ": " + event.getFault());

        }

        

        @Override

        public List<Product> getMergeResultWith() {

            return products;

        }

    });

}

            

public class EntityNotFoundExceptionConverter implements ExceptionConverter {


    public static final String ENTITY_NOT_FOUND = "Persistence.EntityNotFound";

    

    public boolean accepts(Throwable t, Throwable finalException) {

        return t.getClass().equals(javax.persistence.EntityNotFoundException.class);

    }


    public ServiceException convert(

        Throwable t, String detail, Map<String, Object> extendedData) {


        ServiceException se = new ServiceException(

            ENTITY_NOT_FOUND, t.getMessage(), detail, t

        );

        se.getExtendedData().putAll(extendedData);

        return se;

    }

}

            

public class EntityNotFoundExceptionHandler implements ExceptionHandler {


    public boolean accepts(FaultMessage emsg) {

        return "Persistence.EntityNotFound".equals(emsg.getCode());

    }


    public void handle(Context context, FaultMessage emsg, TideFaultEvent faultEvent) {

        System.err.println("Entity not found: " + emsg.getMessage());

    }

}

            

The server data objects are usually defined as JPA entities. Using them directly on the client is possible but requires having a runtime dependency on the JPA provider on the client, which may not be practical or suitable at all. This is for example what would happen by using standard Java serialization. Additionally, using a JPA entity on a JavaFX client (for example) means that your data beans will not benefit from all the data binding machinery of JavaFX which requires the use of special properties implementations (javafx.beans.property.Property). You could probably build a 'dual' Java class which is both a JPA entity and a bindable JavaFX bean but that would imply a very tight coupling between the client and the server (and a dependency of the server application on JavaFX !!) and might at last not work at all (in particular for collection properties).

Having two different classes for the same data object on the client and the server is thus a cleaner approach and simply requires some tooling to automatically generate one from the other. GraniteDS provides a JPA/JavaBean to JavaFX class generator which handles exactly this task.

In many Java EE applications, persistence is done by using a JPA provider (such as Hibernate). The application directly persists and fetch Java entities, so this could seem natural to transfer these same objects to the client layer instead of adding a extra conversion layer with data transfer objects. However this is not as simple as it seems, in particular when using the lazy loading feature of JPA (and most applications using JPA should use lazy loading).

Usual serialization providers (AMF or not) will either throw exceptions during serialization (because the lazy loaded associations are not available at this time), or load the complete object graph and thus limit the applicability of lazy loading (when using patterns such as Open Session in View).

GraniteDS on the other hand is able to reliably serialize JPA entities with its externalizer mechanism (even detached objects outside of a JPA session) and supports both kinds of associations: proxy (single-valued associations) and collections (such as List, Set, Bag and Map). As described in the previous section, it provides built-in support for Hibernate, TopLink/EclipseLink, OpenJPA and DataNucleus.

@Entity

public class MyEntity {


    @Id @GeneratedValue

    private Integer id;


    @OneToOne(fetch=FetchType.LAZY)

    private MyOtherEntity other;


    // Skipped code...

}


@Entity

public class MyOtherEntity {


    @Id @GeneratedValue

    private Integer id;


    // Skipped code...

}

            

package com.myapp.entity;


import java.util.HashSet;

import java.util.Set;


...

import javax.persistence.CascadeType;

import javax.persistence.FetchType;

import javax.persistence.OneToMany;


@Entity

public class Person extends AbstractEntity {

    ...

    @OneToMany(cascade=CascadeType.ALL, fetch=FetchType.LAZY, mappedBy="person")

    private Set<Contact> contacts = new HashSet<Contact>();

    ...

    public Set<Contact> getContacts() {

        return contacts;

    }

    public void setContacts(Set<Contact> contacts) {

        this.contacts = contacts;

    }

}


        // code for Contact skipped...

            

package com.myapp.entity;


    ...

    import javafx.collections.ObservableList;


    @JavaFXObject

    @RemoteClass("test.granite.ejb3.entity.Person")

    public class Person implements Identifiable, Lazyable, DataNotifier  {


        ...

        private ObservableList<Contact> contacts = new PersistentSet<Contact>();

        ...

        public void setContacts(ObservableList<Contact> contacts) {

            this.contacts = value;

        }

        public ObservableList<Contact> getContacts() {

            return this.contacts;

        }


        // code for Contact skipped...

            

Security in a Java client cannot simply rely on standard web-app security-constraints configured in web.xml. Generally, you have only one channel-definition, equivalent to a url-pattern in web.xml, and multiple destinations. So, the security must be destination-based rather than URL-pattern based, and Java EE standard configuration in web.xml does not provide anything like that.

With a configured SecurityService, you will be able to use Channel's setCredentials and logout methods.

Another important feature in security is to be able to create and expose a java.security.Principal to, for example, an EJB3 session bean backend so role-based security can be used.

At this time, GraniteDS provides security service implementations for Tomcat5+, Jetty6+, GlassFish V2+ and V3 and WebLogic 10+ servers. Because JBoss comes with Tomcat by default but may be configured to use Jetty instead, Tomcat or Jetty security services may work as well with JBoss.

When you are using Java Enterprise frameworks such as Seam or Spring together with GraniteDS, you may use specific Seam Security or Spring Security implementations instead of the previous container-based services: please refer to Seam Services or Spring Services for more information.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE granite-config PUBLIC

    "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/3.0.0/granite-config.dtd">

<granite-config>

    ...

    <security type="org.granite.messaging.service.security.TomcatSecurityService"/>

    <!--

    Alternatively for Tomcat 7.x

    <security type="org.granite.messaging.service.security.Tomcat7SecurityService"/>

    Alternatively for Jetty 6.x

    <security type="org.granite.messaging.service.security.Jetty6SecurityService"/>

    For Jetty 7.x/8.x (available at eclipse.org)

    <security type="org.granite.messaging.service.security.Jetty7SecurityService"/>

    For GlassFish 2.x

    <security type="org.granite.messaging.service.security.GlassFishSecurityService"/>

    For GlassFish 3.x

    <security type="org.granite.messaging.service.security.GlassFishV3SecurityService"/>

    For WebLogic

    <security type="org.granite.messaging.service.security.WebLogicSecurityService"/>

    -->

</granite-config>

            

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE granite-config PUBLIC

    "-//Granite Data Services//DTD granite-config internal//EN"

    "http://www.graniteds.org/public/dtd/3.0.0/granite-config.dtd">

<granite-config>

    ...

    <security type="org.granite.messaging.service.security.TomcatSecurityService">

        <param name="service" value="your-tomcat-service-name-here"/>

    </security>

</granite-config>        

            

<?xml version="1.0" encoding="UTF-8"?>

<services-config>

    <services>

        <service id="granite-service"

            class="flex.messaging.services.RemotingService"

            messageTypes="flex.messaging.messages.RemotingMessage">

            <destination id="person">

                <channels>

                    <channel ref="my-graniteamf"/>

                </channels>

                <properties>

                    <scope>session</scope>

                    <source>com.myapp.PersonService</source>

                </properties>

                <security>

                    <security-constraint>

                        <auth-method>Custom</auth-method>

                        <roles>

                            <role>user</role>

                            <role>admin</role>

                        </roles>

                    </security-constraint>

                </security>

            </destination>



            <destination id="restrictedPerson">

                <channels>

                    <channel ref="my-graniteamf"/>

                </channels>

                <properties>

                    <scope>session</scope>

                    <source>com.myapp.RestrictedPersonService</source>

                </properties>

                <security>

                    <security-constraint>

                        <auth-method>Custom</auth-method>

                        <roles>

                            <role>admin</role>

                        </roles>

                    </security-constraint>

                </security>

            </destination>

        </service>

    </services>

    ...

</services-config>

            

public interface RemotingDestinationSecurizer extends DestinationSecurizer {


    public void canExecute(ServiceInvocationContext context)

        throws SecurityServiceException;

}