1. First off, we’re going to change the entity manager that is available for injection to be request scoped. To do this, open up DataRepositoryProducer.java and change the @ConversationScoped annotation on the getEntityManager() method to be @RequestScoped. The reason for this is documented here in A Little Less Conversation.
2. Next we are going to create a simple dao for Course objects, and the only reason to do this is to demonstrate the integration of CDI and the ability to layer your code. Create a new class called CourseDao with the following code.

   package org.fluttercode.restwebdemo.bean;
   
   @Stateless
   @LocalBean
   public class CourseDao {
   
   	@Inject @DataRepository
   	private EntityManager entityManager;
   
   	public void save(Course course) {
   		entityManager.persist(course);
   	}
   
   	public Course update(Course course) {
   		return entityManager.merge(course);
   	}
   
   	public Course find(Long id) {
   		return entityManager.find(Course.class, id);
   	}
   }
   

   This just injects an entityManager and uses it to locate, save and update Course objects.

3. Now create a new CourseService bean that will handle the web services. To start with we want to make it a stateless EJB and inject the course Dao. We are going start by re-implementing the method to return the course name for the given id.

   	@Path("courseName/{id}")
   	@GET
   	public String getCourseName(@PathParam("id") Long id) {
   		Course course = courseDao.find(id);
   		if (course == null) {
   			return "Course not found";
   		} else {
   			return course.getTitle();
   		}
   	}
   

To see this method in action, deploy the application and go to http://localhost:8080/restwebdemo/rest/course/courseName/126. Now we know everything is working and hooked up together, we can look at adding some new functionality.

Let’s start by returning a course with a given id from the service. This is fairly simple given what we already know. The only thing to determine now is what format to return the object as and to convert it to that type. Luckily, Java EE already provides JAXB which can take an object graph and convert it to XML for us as long as we annotate the classes with the annotations to let the JAXB implementation know how to convert it. The same annotations can be used by the body writer that handles JSON.

First we’ll annotate the Course class and make a couple of changes that we need to. Next we’ll create methods to return a Cource object from the service in XML or JSON format.

1. Open the Course class and add the following annotations to the class.

   @Entity
   @XmlRootElement
   @XmlAccessorType(XmlAccessType.FIELD)
   public class Course extends BaseEntity {
      ...
      ...
   }
   

   This tells the JAXB processor that this class can be serialized and to access the values using fields in the class. This also means that any other annotations we want to add to control the serialization needs to be applied to the fields.

This is a simple example, so we don’t want to serialize the teacher or enrolled properties which we can do by marking them with the @XmlTransient attributes. Also, remove the @NotNull annotation from the teacher attribute as we will need it blank later. The following code shows the fields with both the JAXB and JPA annotations. JAXB (like JPA) uses default conventions for fields that don’t have annotations :

	@Column(length = 32, nullable = false)
	@Size(max = 32)
	@NotEmpty(message = "title is required")
	private String title;

	@Column(length = 8, nullable = false)
	@Size(max = 8  )
	@NotEmpty(message = "code is required")
	private String code;

	@ManyToOne(fetch = FetchType.LAZY)
	@XmlTransient
	private Teacher teacher;

	@ManyToMany(mappedBy = "enrolled")
	@XmlTransient
	private List<Student> students = new ArrayList<Student>();

We are just using a simple JAXB model for the sake of the example which is why we aren’t including the Teacher and Student classes.

2. Now in our CourseService class we will create methods to return the course entity and we will create one for JSON and one for XML.

   	@Path("find/{id}/xml")
   	@GET
   	@Produces(MediaType.APPLICATION_XML)
   	public Course getCourseAsXml(@PathParam("id") Long id) {
   		return courseDao.find(id);
   	}
   
   	@Path("find/{id}/json")
   	@GET
   	@Produces(MediaType.APPLICATION_JSON)
   	public Course getCourseAsJson(@PathParam("id") Long id) {
   		return courseDao.find(id);
   	}
   

(note : At this point, I had to switch to using Hibernate as the JPA provider since JAXB didn’t like the interface EclipseLink used for proxying the properties. You can do this using the Glassfish update tool).
If you redeploy the application and browse to http://localhost:8080/restwebdemo/rest/course/find/1/json you should be prompted to save a file, or it will display the text, but the content should be something like :

{"createdOn":"2010-08-27T16:36:57.015-04:00",
  "id":"1",
  "modifiedOn":"2010-08-27T16:36:57.015-04:00",
  "title":"Computing for Beginners",
   "code":"CS101"}

or if you go to http://localhost:8080/restwebdemo/rest/course/find/1/xml you will get an XML version :

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<course>
	<createdOn>2010-08-27T16:36:57.015-04:00</createdOn>
	<id>1</id>
	<modifiedOn>2010-08-27T16:36:57.015-04:00</modifiedOn>
	<title>Computing for Beginners</title>
	<code>CS101</code>
</course>

Now we can grab objects from our web service, we should look at creating objects from the service. We add a new method that takes the title and code values, creates a new Course with those values and saves it using the courseDao.

	@Path("create")
	@PUT
	@Produces(MediaType.APPLICATION_JSON)
	public Course createCourse(@FormParam("title") String title,@FormParam("code") String code) {
		Course course = new Course();
		course.setTitle(title);
		course.setCode(code);
		courseDao.save(course);
		return course;
	}

Here I’ve used the FormParam annotations to plug form values into the method call. You’ll notice that using REST conventions, the method to create a course uses the PUT type of request. Now let’s create a page to enter a title and code and create the course. Notice that our method returns the created course so we can return the course back to the user. This is probably not ideal, but suits for the purposes of demonstration. Now lets create a new HTML page to allow for data entry and calling the web service to create the Course.

<html>
<head>
<title>Insert title here</title>
<script type="text/javascript"
	src="http://localhost:8080/restwebdemo/jquery-1.4.min.js">
</script>
</head>
<body>
<div id="message"
	style="display: none; background: #d0d0f0; padding: 12px">Message Div</div>
<form action="rest/course/create" method="POST">

    <fieldset>
    	<legend>Create Course</legend>
    	<p>
	        Title<br />
    	    <input id="title" /><br />
    	</p>
    	<p>
        	Code<br />
        	<input id="code" /><br />
    	</p>
    	<input type="submit" id="submit" />
	</fieldset>
</form>
</body>

<script type="text/javascript">

//jquery pieces
$(document).ready(function() {

    //change the submit button behaviouus.
    $('#submit').click(function () {
		var title = $("input#title").val();
		var code = $("input#code").val();

		params = "title="+title+"&code="+code;
		//alert("posting form : "+data);
        $.ajax({
               type: "PUT",
               url: "rest/course/create",
               data: params,
               success: function(result) {
        		   showMessage("Created Course "+result.title+" with id "+result.id+" on "+result.createdOn);
               }
        });
		return false;
    });
});

function showMessage(msg) {
	  $('#message').html(msg);
	  $('#message').fadeIn('fast');
	   $('#message').delay(3000).fadeOut('slow');
}
</script>
</html>

This looks a lot code, but not really. We import jquery to help us post our form, and we create our form with the two fields. We use JQuery to add an event handler so when you click submit, it packages up the form, calls our web service with a PUT type of request and grabs the returned object as a JSON object, and displays a message using the values from the new instance obtained from the server. To verify that your course has been created, go to the front page and you should see it listed.

That about wraps it up for this post, the source code can be downloaded from (restwebdemo_pt2), just unzip it, use mvn clean package and deploy the war to glassfish and use the URLs mentioned in the article.

]]> http://www.andygibson.net/blog/tutorial/simple-restful-services-in-glassfish-pt-2/feed/ 0 http://www.andygibson.net/blog/article/simple-restful-web-services-with-glassfish/ http://www.andygibson.net/blog/article/simple-restful-web-services-with-glassfish/#comments Thu, 03 Feb 2011 13:44:52 +0000 Andy Gibson http://www.andygibson.net/blog/?p=1723 Here’s a quick guide to creating a RESTful web service with Glassfish using JAX-RS.

First create a new maven project called restwebdemo using the jee6-sandbox-archetype so we have a model and some data to work with. To get this working with Glassfish, open the persistence.xml file and change the jta-data-source name to jdbc/__default. Also, make sure that the javaDB is up and running by going to $glassfish_dir/bin and typing asadmin start-database. Verify that the application is working correctly by going to http://localhost:8080/restwebdemo/ and you should get a list of courses.

Before we start getting to the interesting stuff, we have one more boring piece of configuration to perform specific to web services. We need to add the jersey servlet container to our web.xml file:

<servlet>
	<servlet-name>Jersey Web Application</servlet-name>
	<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
	<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
	<servlet-name>Jersey Web Application</servlet-name>
	<url-pattern>/rest/*</url-pattern>
</servlet-mapping>

This also tells Jersey to handle urls starting with /rest and pass it along to our web service methods.

Now we can dive right in an create a new server bean that will respond to requests for web services. For now we’ll just return a simple message from a POJO.

@Path("sample")
public class SimpleService {

	@Path("greet")
	@GET
	public String doGreet() {
		return "Hello Stranger, the time is "+ new Date();
	}
}

The path annotation on the class indicates that this is a root resource class and the path value given specifies the base URI for all the web service methods contained in the class.
On the doGreet method we have @Path which is used to specify the path template this method should match. The @GET annotation is used to differentiate between a sub-resource method that handles the actual web service request and a sub-resource locator method that returns an object that will instead be used to handle the request. In this case, the method has the @GET annotation which means this method handles the request and returns the result.
If you navigate to http://localhost:8080/restwebdemo/rest/sample/greet/ you should see a welcome message with the current date and time.

Now we’ll look at adding parameterized web services that extracts parameters from the request URL and uses them to form the output. Add the following method to the web service class :

@Path("sayHello/{name}")
@GET
public String doSayHello(@PathParam("name") String name) {
	return "Hello there "+name;
}

Again we have the path annotation to indicate what URLs this method will match, and this time we have have {name} added to the URL. This lets us extract a part of the url and give it a name. This name is used in the @PathParam annotation in the method signature to assign the URL fragment to the name parameter . To test our new method, redeploy the application and go to the URL http://localhost:8080/restwebdemo/rest/sample/sayHello/Andy to get the response Hello there Andy

We can also use request parameters to provide values to the method by using the @QueryParam annotation. We’ll create another method that is similar but uses a query parameter instead.

@Path("sayHello")
@GET
public String doSayHelloWithRequestParam(@QueryParam("name") String name) {
	return "Hi there "+name;
}

This time, the URL to use is http://localhost:8080/restwebdemo/rest/sample/sayHello?name=Andy to get the same message.

To make things more interesting, lets add a new page that lets us enter a name in a form and submit it to the web service. Add a new page called form.html with the following content :

<html>
<head>
<title>Insert title here</title>
</head>
<body>
<form action="rest/sample/sayHello" method="GET">
Name <input id="name" name="name"/> <input type="submit" />
</form>
</body>
</html>

Go to this page at http://localhost:8080/restwebdemo/form.html, enter your name and click submit and you should be greeted by name in the next page.

Notice that we had to set the form method to GET because our web service is only set up to respond to GET requests. If we change the form method to POST we can get the following error message :

HTTP Status 405 - Method Not Allowed
type Status report
message Method Not Allowed
description The specified HTTP method is not allowed for the requested resource (Method Not Allowed).

Remember, with REST, those actual verbs have meaning and adds meaning to the request so it is strict on how it matches the method to be called.

To solve this problem, we can add a new method to handle form POSTs like so :

@Path("sayHello")
@POST
public String doSayHelloWithFormParam(@FormParam("name") String name) {
	return "Hi there " + name;
}

Here we changed the @GET to a @POST to allow the different verb and changed the annotation on the name method parameter to @FormParam. The path remains the same because we can have service methods that match the same path, but for different request verbs. We can even have the same verb and path as long as the content type returned is different. The content type is used to specify the type of output the is returned from the method. It is set by adding a @javax.ws.rs.Produces (not to be confused with the CDI Produces annotation). The annotation takes a string parameter that indicates the type of media returned from the method. Common media types are defined as constants in the MediaType class so you can use :

@Path("sayHello")
@POST
@Produces(MediaType.APPLICATION_XML)
public String doSayHelloWithFormParam(@FormParam("name") String name) {
	return "<message>Hi there " + name+"</message>";
}

If you run your form again, and post it, you will get an xml response as follows :

<message>Hi there Andy</message>

Depending on your browser, if you return just the text, you will get an error because the plain text isn’t valid XML and the browser expects XML because that is the response type set on the response from the web service.

To finish up, we are going to do something a little more interesting, we will create a web service to return the name of a course from the database using the sandbox data built into the archetype. For various reasons, we will take the most direct route to getting data access which is to make the web service bean a stateless bean and inject a persistence context using the @PersistenceContext annotation.

1. Add the @Stateless annotation to the SimpleService class and an entity manager field annotated with @PersistenceContext along with the getters and setters.
2. Add a new method to return the course name for the given course id parameter. We will return it as text for the time being :

   @Path("courseName/{id}")
   @GET
   public String getCourseNameFromId(@PathParam("id") Long id) {
   	Course c = entityManager.find(Course.class, id);
   	if (c == null) {
   		return "Not Found, try the index <a href='/restwebdemo/'>page</a> and come back";
   	} else {
   		return c.getTitle();
   	}
   }
   

   Note that the automatic type conversion takes place and the value is converted to a Long automatically. If the course is not found, we suggest the user goes to the main page of the demo. We aren’t just being overly helpful, the test data is generated when you request one of the application pages for the first time. In the current persistence context, when you redeploy, the database is dropped and rebuilt so it will be empty. You need to go to the front page to automatically create the data and then go back to your page to view the course. An example URL is http://localhost:8080/restwebdemo/rest/sample/courseName/124.

Of course you could grab the course object and build your own XML or JSON response to send back to the client, or use a third party library like Jackson to build the JSON response. However, as we’ll see next time, Java EE 6 has all these goodies built in for us, and with a few annotations, we’ll be slinging objects back and forth in no time at all.

You can download the source code for the project from here. Simply unzip, build with maven (mvn clean package) and deploy to Glassfish.

]]> http://www.andygibson.net/blog/article/simple-restful-web-services-with-glassfish/feed/ 3 http://www.andygibson.net/blog/quickbyte/updating-weld-in-glassfish-v3/ http://www.andygibson.net/blog/quickbyte/updating-weld-in-glassfish-v3/#comments Tue, 27 Jul 2010 14:08:40 +0000 Andy Gibson http://www.andygibson.net/blog/?p=1146 (updated : This post refers to Glassfish installations prior to version 3.0.1 which was recently released and includes Weld version 3.0.1. Given the new version, this manual update is not necessary and should not be performed if you have an updated installation of Glassfish 3.0.1+)

Even some of the recent versions of Glassfish include a version of Weld, the reference implementation for CDI (JSR 299), that has some major issues. Since Glassfish uses OSGI, upgrading isn’t as easy as just replacing the jar with a new one. This tutorial shows you how to upgrade Glassfish to Weld 1.0.1.Final as well as including a pre-built distribution of the two files that need re-deploying.

One of the ways to get around the faulty version of Weld currently in Glassfish is to moving up to Glassfish 3.0.1 nightly builds (update : 3.0.1 has been released and should be used) . A less bleeding edge solution would be to upgrade the version of Weld that is deployed on your current version of Glassfish by updating the weld-integration and weld-osgi-bundle jar files. However, one must be careful of the integration jar version as one of the major interfaces changed after the initial release of Weld introducing incompatibilities.

Updating the OSGI bundle is easy since it can be built from the Weld source code. Just download and compile it and locate the osgi-bundle.jar file.

We also need to grab a new version of the weld-integration.jar file. There are all sorts of versions of this file, but the one I found working for Weld 1.0.1.final was version 3.0.1-b11/.

I’ve already built the osgi-bundle and grabbed the integration jar and verified that they work so I’ve renamed and zipped them so you can just download and unzip them into the modules directory of your Glassfish v3 installation.

This is also a necessary step to get the Knappsack Java EE 6 demo project working under Glassfish. You can find more details on the server compatability page

]]> http://www.andygibson.net/blog/quickbyte/updating-weld-in-glassfish-v3/feed/ 2 http://www.andygibson.net/blog/news/java-ee-6-is-here/ http://www.andygibson.net/blog/news/java-ee-6-is-here/#comments Fri, 11 Dec 2009 00:13:19 +0000 Andy Gibson http://www.andygibson.net/blog/?p=689 Like Christmas come early, Sun announced the release of JEE 6. This release sees continued improvement in the JEE stack with the inclusion of JSR 299, Java Contexts and Dependency Injection (CDI), and EJB 3.1 as well as JSF 2.0, and JPA 2.0. JSF especially has seen changes as a result of practical user feedback and community add-ons such as Seam and JSF Ajax frameworks which have contributed back to the JCP.

Glassfish v3 which implements the full JEE 6 stack has also been released, with JBoss’ Weld as the CDI implementation. Netbeans 6.8 has also been released with full JEE 6 project support including maven support for enterprise applications. Also of note is the hot deploy function of Glassfish which can deploy your app while maintaining session information.

Personally, I’m pleased. JEE 6 has really improved things for the java standards, and CDI has filled some gaps that previously required different additional pieces to completely fill. The ghosts of EJB 2.1 should now be permanently laid to rest, but should serve as a stark reminder. Having good frameworks to build standards based solutions is always good for the community.

I’ll try and get some tutorials on developing with CDI and JSF 2.0 with Netbeans and Glassfish out soon.

]]> http://www.andygibson.net/blog/news/java-ee-6-is-here/feed/ 1