Fulworx provides Struts-like functionality for restful interfaces to applications by leveraging XWork, Restlets, and JAXB2 to perform CRUD functionality. Think of this: Struts is to Servlet what Fulworx is to Restlet.

How? Standard XWork Actions are annotated with a few annotations, and the framework will deploy them as restful services. These same actions can be used with Struts2 or WebWork with very little overhead, simply create a struts.xml (or webwork.xml) and invoke the action.

Release 2.2 is complete

See features below, or visit the manual: V2.2 Documentation

If you're having issues or questions, check out the FAQ

Check out the JavaDoc

Check out the Samples

Previous Releases

V2.1 Documentation

V2.0 Documentation

V1.X Documentation

Overview

XML and URI parameters are mapped into XWork Actions providing a clear separation of layers. A URI such as

"/someURI/user/squarepants/spongebob"

 <user>
   <email>user@somewhere.com</email>
   <phone>555.123.4567</phone>
 </user>

is mapped to an action like:

@URITemplate(uri="/someURI/user/{lastname}/{firstname}")
@Accessor("user")
public class UserAction implements CreateAction, ReadAction
{
    private User user;
    private String firstname;
    private String lastname;
    private UserService userService;

    public UserAction(UserService service){
        this.userService=service;
    }

    public String create()
    {
        user = this.userService.create(firstname,
                                       lastname,
                                       user.getEmail(),
                                       user.getPhone());
        if(user == null){
          //if user isn't found, insert firstname and lastname into 
          //resource bundle message, and return a 404 status code
          throw new ApplicationException(
            new BundledErrorDetail("user.error.notfound",
                                   ResourceBundle.getBundle("ErrorMessages"),
                                   new Object[]{firstname, lastname}),
            404);
        }
        return SUCCESS;
    }

    public String read()
    {
        user = this.userService.read(firstname, lastname);
        return SUCCESS;
    }

    public User getUser()
    {
       return user;
    }

    public void setUser(User user)
    {
       this.user = user;
    }
    //also, getter / setter for firstname, lastname
}

would create a user on the system and respond with:

 <user>
   <id>1</id>
   <firstname>spongebob</firstname>
   <lastname>squarepants</lastname>
   <email>user@somewhere.com</email>
   <phone>555.123.4567</phone>
 </user>

The user object with JAXB annotations looks something like:

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "", propOrder = {
        "id",
        "firstname",
        "lastname",
        "email",
        "phone"
        })
@XmlRootElement(name = "user")
public class User implements Serializable
{
    @XmlElement(name = "id", required = false)
    protected Integer id;
    @XmlElement(name = "firstname", required = false)
    protected String firstname;
    @XmlElement(name = "lastname", required = false)
    protected String lastname;
    @XmlElement(name = "email", required = true)
    protected String email;
    @XmlElement(name = "phone", required = false)
    protected String phone;
    
    //all appropriate getter / setter methods
}

HTTP methods are mapped to CRUD functionality following the rules:

• PUT = create
• GET = read
• POST = update
• DELTE = delete

Other Features

Media Types (Content Type)

Specify a media type with the @URITemplate and you can serve different resource types and versions with the same uri. These are also cached per URI and media type. Media type and Content type are the same thing here. See the URI Templates Documentation.

Caching

To cache the UserAction's read method, various cache annotations are available at the class level. Calls to 'update', 'delete', and 'create' update the cache appropriately. See the Cache Documentation

Interceptors

Actions support interceptors, and may be configured or added as annotations. See the Interceptor Documentation

Guards

A resource could use Restlet Guards as well. See the Guards Documentation.

Representations

Other representations of this xml can be retrieved by very simple changes to the uri:

• "/someURI/user/spongebob/squarepants.xml" will return xml (default)
• "/someURI/user/spongebob/squarepants.json" will return JSON
• "/someURI/user/spongebob/squarepants.badgerfish" will return badgerfish
• "/someURI/user/spongebob/squarepants.xsd" will return the schema

you may also specify media type instead for the same default JAXB resource:

• application/x-xsd+xml (returns a schema)
• application/xml (returns xml)
• application/json (returns json)
• application/badgerfish (returns badgerfish)
• text/* (for strings)

Other representations are available by using media types and specifying an @Accessor.type. This could be other versions of XML, or something other than XML altogether.

For custom representations, see the Accessor Documentation.

For other media types to a URI, see the URI Documentation.

Default XML

Common success strings are put into a simple xml for successes. Errors and exceptions are put into a standard error list for response and analysis by end users. See the Fulworx XML Documentation.

Custom Errors

When an error happens, you can specify the class that creates the error result by using the @ResponseError annotation. The type of representation depends on the @Accessor representation type. See the Errors Documentation.

To learn more, check out the Main page.