Junos Space SDK > Developer Guides > Junos Space Application Developer Guide > Programming with the Junos Space SDK > Using the Junos Space SDK Plug-in > Using the EJB-REST Wizard

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:

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.

button

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:

first wizard interface Page

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.

second_resource_page

Important dialog sections:

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:

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: 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:








Let's see what the preview displays when population field is turned on (left part of the screenshot) and when turned off (right part):

<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.