Getting Started (EJB Project, RESTification, and Application Deployment)

Table of Contents

1. EJB Project
   1. EJB Interface and Implementation
   2. EJB Methods
   3. Managed Objects
2. HelloWorld Ejb RESTification
   1. Resource Creation
   2. Method RESTification
      1. Configure REST Method tab
      2. REST Method Preview Tab
   3. Editing DTO
3. Deploying Application

In this section, we will use the HelloWorld sample application as an example. To import a HelloWorld application, start with an empty workspace, then navigate to the file browser and open the archived application. To reach the browse dialog, access the Eclipse top menu, File > Import... > General > Existing Projects Into Workspace > Select Archive File and the click on Browse... . Navigate to the sample applications subfolder and select the HelloWorld.zip file.

Archived applications are located in:

On Mac:
    ../Juniper Networks/Junos Space SDK/docs/samples/Sample Applications

On Linux:
    ../Juniper_Networks/Junos_Space_SDK/docs/samples/Sample Applications

On Microsoft Windows:

    C:\Program Files (x86)\Juniper Networks\Junos Space SDK\docs\samples\Sample Applications
            or
    C:\Program Files\Juniper Networks\Junos Space SDK\docs\samples\Sample Applications

EJB Project

The HelloWorldEJB project contains business logic as the EJB interface and implementation class, as well as managed object classes. The project is registered in the HelloWorld EAR project as an EJB JAR component, and is deployed to the platform as a part of the whole application package.

EJB Interface and Implementation

The HelloWorld EJB interface exposes business method signatures that can be called from a RESTful service.

The HelloWorldImpl bean contains the actual business logic and Hibernate APIs and HQL queries to persist Hibernate Entities. The @Stateless annotation sets up the bean name and is used by the Web services to look up or obtain the bean handles. The bean class must implement its remote interface and reference the interface in the @Remote annotation.

EJB methods

Any business method should be declared an EJB interface and an EJB implementation class. The EJB implementation class can also contain private utility methods:

Managed Objects

EJB interface methods use managed objects as either parameters or return values. Each managed object is a simple Java Bean, having a default constructor as well as a set of properties, where each property is defined by a field and properly named getter and setter methods. Collections of managed objects are also acceptable as method parameters and return values.

Commonly accepted types for a managed object property are the following:

• Primitive type (for example, int, boolean)
• java.lang.String, java.lang.Integer, etc.
• Other managed objects.
• Collection or list with template argument of other accepted type.
• net.juniper.jmp.PagingResult with template argument of other accepted type.
• Array of other accepted type.

Managed objects can reference other managed objects, such as Country and State in the HelloWorld example. The REST Wizard takes this type of relation into consideration during EJB RESTification.

Country has a field of List of State type:

HelloWorld EJB RESTification

Resource Creation

To expose the EJB method as a method of a REST service, the EJB method should be RESTified. The first step is to launch the REST Wizard by clicking on the "Manage REST Services" button in the Eclipse toolbar.

The first table lists all existing REST services, which were created using the REST Wizard.

The first step of EJB RESTification is Resource (or Service) creation. Service management buttons are located under the table:

The New Service, Edit Version, and Delete Version buttons manage the service life cycle. It is possible to create a new version of an existing service to RESTify the same EJB methods in another way, or to add more methods to the service. Versions of a service are displayed both in documentation and INFO service, the client is able to choose which version of a service to call. It is also possible to deprecate any particular service version, effectively removing any mentions of that service from the documentation.

Clicking the New Service button displays the new service editor:

The first thing to do in this dialog is to specify the EJB interface to restify by clicking the Browse... button that will open interface search dialog. The Wizard will try to find the interface implementation class (EJB class) automatically, but the user can specify the class manually in the same way as the interface. The Target Context combo indirectly specifies a web service project to put RESTified service into. The Target context is a URL prefix for a Web service project, which is set in the META-INF/application.xml file of the EAR project (HelloWorld project for the sample application). Note that there is no way to automatically update the @HATOEAS annotation href attribute values in the already generated REST code if the project context root is changed in the EAR. The best bet in this case is to select a REST service project and perform a text search for the old project context root, then click through the search results making sure it is about the @HATEOAS annotation, and changing the project context root URL part to the new one.

Clicking the Next button displays the REST service methods editor.

Important dialog sections:

• Service Root—A part of the service URL that is unique for the service. The complete service URL is the project target context and service root combined. In the example, the /api/jssdk/hello-world context root of the HelloWorldWebSvc project and the /hello-world service root of the RESTified HelloWorldEJB results in a /api/jssdk/hello-world/hello-world service URL.



• Methods of EJB Interface—Yet unRESTified methods of the EJB interface. These methods are not exposed by REST.
• Methods of REST Interface—Already RESTified methods of the EJB interface. Method RESTification moves the method from the Methods of EJB Interface table to the Methods of REST Interface table.
  

The following buttons control method RESTification:

1. "+REST All"—RESTifies all available EJB methods. Sets each restified method properties to the default. Generally, selecting this button is enough to RESTify the service.
2. "+REST"—Opens a single method RESTification wizard.
3. "-REST"—Unrestifies the method.
   

The following actions are available for an already restified method:

1. "Edit"—Opens the method editor.
2. "Patch"—Adds PATCH support for the method. To add PATCH support to a method, all CRUD methods must be RESTified for a DTO.
3. "REPORT"—Opens a dialog displaying request and response samples for each RESTified method.

Method RESTification

Often, default method properties are fine enough for a RESTification, and all a user needs is to do is click the "+REST All" button. But sometimes the user might want to configure method restification in details. The "+REST" button for an EJB method and the "Edit" button for a REST method opens the method restification wizard.

Configure REST Method tab

Tab points of interest:

• HTTP method to map the current REST method to. For GET methods, the Request Message Body section is unavailable for GET methods.

• Method URL editor. Full method URL path is combined from the REST service URL and method URL path.
  

• Method parameter editor and order controls.

• Media type editor. Available for both request body and response body. It is not recommended to change the value.

• Supported formats combo. Default XML+JSON is recommended.

The Parameters table supports in-place editing, click on a value to activate the editor.

In the example, the simple type parameters support name and category in-place editing:

The following method parameter categories are available:

1. Path—Path category means that the parameter value will be parsed from a part of the URL path. In the example, for the /api/jssdk/hellow-world/countries/{country-id} URL ({country-id} is path parameter), the invocation of /api/jssdk/hellow-world/countries/15 URL will set the REST method countryId parameter value to 15.
2. Query—Query category means that the parameter value will be parsed from the Query part of the URL. In the example, the /api/jssdk/hellow-world/countries?sort-mode={sort} invocation of the /api/jssdk/hellow-world/countries?sort-mode=desc URL will result in the sort parameter value being set to desc.
3. Body—Body category means that parameter will receive an instance of a class, restored from XML or JSON in message body.
4. Context—Utility parameter means its value will be automatically inserted by the framework. This category cannot be changed.

REST Method Preview tab

The Preview tab displays request and response samples for a method. For the addCountry method, this method has DTO Country as the body parameter, and returns the same DTO. The following information will be displayed on the Preview tab for addCountry:

• HTTP method
• URL, current REST method is bound to.
• Accepted and returned media type
• Request sample
• Response sample

HTTP Method: POST
URL: /api/jssdk/hello-world/hello-world/countries

	Query Parameters: 
	Request Message Media Types: 
		application/vnd.jssdk.hello-world.hello-world.country+xml;version=1;charset=UTF-8
		application/vnd.jssdk.hello-world.hello-world.country+json;version=1;charset=UTF-8
	Response Message Media Types: 
		application/vnd.jssdk.hello-world.hello-world.country+xml;version=1;q=0.01
		application/vnd.jssdk.hello-world.hello-world.country+json;version=1;q=0.01

	Example Request: 
		POST /api/jssdk/hello-world/hello-world/countries
		Authorization: Basic xxxxxxxxxxxxxx
		Accept: application/vnd.jssdk.hello-world.hello-world.country+xml;version=1
		Content-Type: application/vnd.jssdk.hello-world.hello-world.country+xml;version=1;charset=UTF-8

		<country>
		     <name>String</name>
		     <population>Integer</population>
		</country>
		
	Example Response: 
		HTTP/1.1 202 Accepted
		Content-Type: application/vnd.jssdk.hello-world.hello-world.country+xml;version=1;q=0.01
		Content-Length: nnn

		<country href="/api/jssdk/hello-world/hello-world/countries/{id}" uri="/api/jssdk/hello-world/hello-world/countries">
		     <id>int</id>
		     <name>String</name>
		     <population>Integer</population>
		     <states uri="/api/jssdk/hello-world/hello-world/countries/states">
		          <state href="/api/jssdk/hello-world/hello-world/states/{id}" uri="/api/jssdk/hello-world/hello-world/countries/states/{id}">
		               <id>int</id>
		               <name>String</name>
		          </state>
		     </states>
		</country>

Editing DTO

Method return value and its body can be edited by clicking the "Edit" button. This displays the DTO editor:

DTO Editor points of interest:

• Any DTO can be either mapped to a URI, or not. "Mapped to URI" means a method that returns such a DTO exists.
  

• If the current DTO is mapped to a URI, a URI value can be edited. The REST Wizard also tries to estimate the value by examining existing methods. This URI is a URI of the method that returns the current DTO. The URI consists of two parts: the one set for this DTO parent (which is not editable), and the part related to the DTO itself (which can be edited).
  

• Any DTO can be either an Object or a Reference. Reference is a DTO that has the href attribute pointing to the same logical object in its primary collection (a URL that actually manages the object's lifecycle). Object assumes there is either no primary collection for the DTO, or the current method is a part of the primary collection.

• Href can be entered by a user. It must point to an existing RESTified method, and href parameters must map correctly to the DTO fields. Otherwise, validation errors appear.

• Any DTO results in an XML tag or JSON element. Its name can be set in the XML Root editor.

• Fields allows selecting what fields will appear in the XML or JSON representation. Unselecting fields reduces document size. For a body/request DTO it is possible to select what fields are required, and what are optional. The same Country DTO is used for both input and output, but input often requires less fields to be specified then output. For example, when creating a new country by invoking the addCountry method, the idfield should not be specified by a user. In such a case, the id field is optional, and other fields are required.

• "Edit" button provides the user with a more detailed editor for specific fields. Include another DTO editor, if the field has a complex type.

<state href="/api/jssdk/hello-world/hello-world/states/{id}">
     <id>int</id>
     <name>String</name>
     <population>Long</population>
</state>

<state href="/api/jssdk/hello-world/hello-world/states/{id}">
     <id>int</id>
     <name>String</name>
</state>

Managed objects can reference other managed objects. In the example, Country contains a collection of States. This directly affects the DTO generated from these managed objects. In this particular case, the DTO Country has a states field of DTO States type, and the States DTO in turn has a states field of State DTO type. The States DTO is synthetic (there is no managed object, directly mapped to this DTO), created to represent a collection of states.

Let's see the State DTO inside States DTO inside Country DTO. State has an href field, which points at the state primary collection, and the collection of states inside the Country is a subset of the primary collection. Let's check Country in the REST Explorer

The Brazil DTO contains single DTO of State type Bahia. As we can see, this DTO contains only two fields, while the original State inside the primary collection has three fields:

If we follow the href of this State, as displayed in the following screenshot:

we will see the same logical state in its the primary collection, so the states collection inside the Country DTO references its primary collection member counterparts:

Deploying an application

To start deployment, click on a Build/Deploy Junos Space Application in the Eclipse tool bar.

After deployment is finished, open the REST Explorer to test the application by clicking on a button in the Eclipse tool bar.

To expand the tree and open the HelloWorld root node, double-click on the following nodes in the Junos Space Services tree in the left: api > jssdk > hello-world > world:

HelloWorld service contains two collections: Country and State . To see Countries collection, double-click on respective node:

The list of all countries is displayed. Double-click on the Brazil node to see the results of a single country GET request:

Let's create a new country. Select the countries node, and change the HTTP method type to POST. The Body Editor becomes active. Click the Insert XML Template button in the top-right corner of the Body editor. This automatically generates an XML template suitable for this method type. Insert some values into the template, such as those displayed in the screenshot, and click Go.

The Tree Viewer displays the new country in the tree. An XML representation of this DTO is returned as a response body and displayed in the Response viewer.

To remove the country, select it in the tree, change HTTP method to DELETE, and click Enter to launch the DELETE HTTP request to the respective country URL.