NetBeans 6.0 Milestone 10 REST Support Engineering Plan

This is the milestone 10 engineering plan for the RESTful service support in NetBeans 6.0.


Given the feature freeze date is 6/15, we do not have time to add major new features in milestone 10. Therefore, we will defer features such as schema migration, model facade generation and ATOM support to a future release (likely via the Update Center.) Instead, we will concentrate on improving upon and stabilizing what we already have in NetBeans 6.0 Preview release and add new features that are implementable during this time frame.

Here are the high-level requirements for milestone 10:

  • Add support for JSON.
  • Add support for generating skeleton RESTful service code not tied to an entity class.
  • Improve usability of GoogleMap support.
  • Improve test client support for PUT and POST operations.
  • Improve existing wizard for generating RESTful services from entity classes.
  • Improve internal retrieval of entity instances from URIs.
  • Ant script extension.
  • Write unit tests.
  • Improve code generation performance.
  • Fix ClassCastException after redeployment.

Functional Specifications

This section provides high-level functional descriptions of the requirements. For features requiring more detailed specifications, we will add them here as they become available.

REST Component Palette

REST Palette will display REST components from NetBeans partner in addition to well-known resources such as Google Map or Yahoo Search.

WSDL-based REST Integration:

When an icon from the REST Component Palette is dropped onto a REST resource java file, the corresponding WSDL-based web services operation invocation is wrapped in the GET method of a generated REST resource. JAX-WS web service client would also be created if not already exists. The target REST resource class will also get a sub-resource method that give access to the WSDL operation wrapper resource. Unmatched input parameters are specified as query parameters.

Simple WSDL-based REST Service Demo.

JSON Support (not make it to M10).

JSON (JavaScript Object Notation) is a lightweight data-interchange format based on the JavaScript Programming Language. It is a very popular format in the Web 2.0 community, more so than XML. Therefore, we need support it as a mime type for the REST representation.

JAX-WS RI already has an extension for supporting JSON based on Jettison (a JSON StAX Implementation that makes use of JSONObject) in combination with JAXB. It can serialize JAXB-annotated class instances into JSON and back. The same approach can be implemented in the REST runtime. This means that our JAXB-annotated converter classes can be reused without any modification to support JSON. We only need to generate additional HTTP methods with JSON as the mime type. It is up to the REST runtime to marshal the converter instances into the right format.

Note that in case the JSON support does not make it into the runtime, we can consider bundling the JSON library code and make calls directly in our generated code.

We also need to enhance our test client to support JSON.

Issue: Should we allow the user to specify whether they want to generate support for XML, JSON or both?

Non-entity Based RESTful Services

We need to support generation of skeleton RESTful services not tied to entity classes. The skeleton code will contain pre-generated HTTP methods for working with XML and JSON formats. We will support the container-item and singleton patterns. The container-item pattern will be similar to what we generate for the entity classes. The container resource will contain HTTP methods for GET, PUT and POST. The item resource will contain HTTP methods for GET, PUT and DELETE. For the singleton pattern, we will simply generate a top-level resource with HTTP methods for GET, PUT, POST and DELETE.

The wizard for this feature will allow the user to specify the package name, resource name and pattern. For the container-item pattern, we will perform proper pluralization and singularization on the specified resource name.

Improve GoogleMap Support

One of the criticisms we got for our GoogleMap support is that it feels like a prototype. Therefore, we need to improve it. One of the suggestions is to componentize the GoogleMap resource and put it in a palette so users can dnd it on to an existing resource. However, this would look like an overkill if we only have a single GoogleMap component in the palette. Therefore, we plan to add a couple more components such as Yahoo News Search.

Note that for M10, we do not plan to make the palette extensible. This is because it will require us to publish a public API which will require architectural review. We do not have time for that.

Improve PUT and POST Support for the Test Client

Currently, the support for PUT and POST requires users to enter an XML document in a text area. This is not very user friendly. In order to improve this, we need to generate a form based on the XML schema generated from our JAXB-annotated converter classes.

The form can be structured in a tree or in the JSON format.

Improve Existing Wizard

The existing wizard for generated RESTful services from entity classes does not allow users to select a subset of the entity classses, nor does it support calculating the closure. We need to improve this. We can reuse some of the existing code in the JPA modules provided that they are migrated to Retouche.

Improve Internal Retrieval of Entities from URIs

In the Preview release, the way we internally retrieve entities from URIs embedded in a XML document is by sending a HTTP GET request to the server and get the representation in XML. We then deserialize the XML document using the converter which, in turn, creates a copy of the entity instance. Furthermore, we need to merge the copy with the actual entity instance in the persistence context. As you can see, we need to go through quite a few hoops to get the actual entity instance. This is very inefficient. The proper way, in my opinion, is for the runtime to provide us with a way to get the resource instance given an URI. We can then ask the resource instance for the entity instance.

We need to discuss this with the runtime team to come up with a proper solution.

Ant Script Extension

Currently, we hard code the ant task for deploying RESTful services in the build-impl.xml for the web project. We need to switch to using the new ant script extension API.

Write Unit Tests

We need to first set up the test infrastructure for our code base and then start writing unit test cases for the code we develop.

Improve Code Generation Performance

The performance for generating code from a small set of entity classes is not very good. We need analyze this and improve it. We will treat this as a bug and address it after the feature freeze.

Fix ClassCastException after Redeployment

We are still getting ClassCastException occasionally after redeployment even though we are closing the PersistenceManager after each request. We need to get to the bottom of this and fix it. We will treat this as a bug and address it after feature freeze.

Note that the current workaround for this issue is to close the PersistenceManager after each request. However, this seems to only alleviate the problem instead of solving it. So, if we can find the real solution, we should also look into removing the need to close the PersistenceManager after each request. We may also want to look into turning our PersistenceService into a managed service so we can use code injection to instantiate the PersistenceManager.

QE Plan

Testing REST Services

Documentation Plan



  • REST implementation in SWDP


*Date* *Task* *Owner* *Comment*
5/25/07 Unit Test Setup Nam Nguyen
5/30/07 Non-entity Service Generation Nam Nguyen
6/8/07 Enhance Existing Wizard Nam Nguyen
TBD Code Generation Change for Supporting JSON Nam Nguyen This depends on the availability of the JSON support in either the runtime or in the form of a library
post 6/15 Fix ClassCastException after Redeployment Nam Nguyen
TBD Test Client Change for Supporting JSON Ayub Khan Same dependency as above
5/29/07 Improve Usability of GoogleMap Support Ayub Khan
6/5/07 Improve Test Client Support for PUT and POST Ayub Khan
post 6/15 Improve Code Generation Performance Ayub Khan
TBD Runtime Support for Retrieving Entity Given An URI Peter Liu
6/5/07 Ant Script Extension Peter Liu
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo