In the 7.0 version of NetBeans IDE, currently available as a development build, there are two changes to Java EE 6 RESTful web services generated from entity classes that greatly simplify the resulting application:
- JAXB annotations can be added directly to JPA entity classes. This removes the need for converter classes.
- Services are generated as EJB session facades. This reduces the number of generated service classes and simplifies their code.
JAXB annotations in Java code indicate the XML structure that should be generated from that code. Previously, when you generated a RESTful web service from entity classes, NetBeans IDE created converter classes that contained these annotations.
Starting with NetBeans IDE 7.0, you have the option of generating JAXB annotations directly in the JPA entity classes. This not only leads to cleaner code, but should reduce problems that arise between static JPA and runtime JAXB-generation of XML, such as loops in the reference creating infinitely deep XML. When cases arise where you do have to modify the JPA classes by hand, this should be much easier.
Here is the structure of an EE 6 RESTful service created with NetBeans IDE 6.9.1, showing the converter classes.
Here you see the CustomerConverter class annotated with XmlRootElement and XmlElement.
DiscountCode also has an @XmlTransient annotation for the getCustomerCollection method. The @XmlTransient annotation is necessary because Customer and DiscountCode are mutually dependent. The @XmlTransient annotation prevents JAXB Marshaller from failing due to a cyclic dependency.
Note: If you create EE6 RESTful web services from existing entity classes, make certain that they have the necessary JAXB annotations. You may need to add them by hand. In this case, be careful of cyclic dependencies and annotate any affected methods with @XmlTransient.
Here is the structure of an EE 6 RESTful service created with a development build of NetBeans IDE 7.0. Note the absence of converter classes.
The JAXB annotations are directly in the entity classes instead. For example, the Customer class is annotated with XmlRootElement.
When you use NetBeans IDE 7's RESTful Web Service from Database wizard, JAXB annotations are automatically added to the JPA entity classes. You cannot chose not to. However, when you use the Entity Classes from Database wizard, you have the choice whether or not to add JAXB annotations to the entity classes.
Note: NetBeans IDE 7.0 also lets you add JAXB annotations to EE 5 entity classes. However, RESTful web services generated from EE 5 entity classes still have converter classes.
A session facade is a design pattern advertised in the Enterprise BluePrints program. As stated in the Core J2EE Pattern Catalog, it attempts to resolve common problems that arise in a multi-tiered application environment, such as:
- Tight coupling, which leads to direct dependence between clients and business objects
- Too many method invocations between client and server, leading to network performance problems
- Lack of a uniform client access strategy, exposing business objects to misuse
A session facade abstracts an application's underlying business object interactions and provides a service layer that exposes only the required functionality. Thus, it hides from the client's view the complex interactions between the objects. The session bean also manages the life cycle of business objects. The session bean creates, locates, modifies, and deletes objects as required by the workflow.
When NetBeans IDE does not create session facades, the IDE creates separate service classes for entities and collections of entities. The following illustration shows the project structure of an EE 6 RESTful service created from a database using NetBeans IDE 6.9.1.
By creating services as session facades, the development version of NetBeans IDE only needs to create one service class for each entity class. The following illustration shows the project structure of an EE 6 RESTful service created from the same database as the NetBeans 6.9.1 project, but with the service classes generated as session facades.
Note that NetBeans IDE creates an abstract session facade class. This abstract class contains the code used by all service classes for managing entities. This code includes criteria queries as defined by the EE 6 Criteria API (JPA 2.0).
The other service classes extend the abstract session facade and call on its methods for a specific entity class. Here, the CustomerFacadeREST class calls the methods of AbstractFacade, replacing the generic class parameters with references to the Customer entity class.
The service classes are easy to read, consisting of HTTP method-annotated method calls that refer back to the abstract class. Compare the CustomerFacadeREST session facade, which is 89 lines long...
...to the CustomerResource class generated by NetBeans IDE 6.9.1. CustomerResource is 211 lines long. It includes not only GET, PUT, and DELETE methods, but all the entity management code and dynamic instances of the other service classes.
Here you can see quite clearly that the use of session facades results in simpler code, and a lot less of it! Customizing and maintaining this code should also be much easier.