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

Configuring the REST Services

This topic explains how to configure REST services using the EJB-REST wizard. You can use the EJB-REST wizard to expose EJB methods as REST services. For RESTification, an EJB method must follow certain guidelines. For more information about these guidelines, see the Guidelines for RESTification of EJB Methods topic.

Creating a REST Resource

You can create a new REST Resource by accessing the Eclipse EJB-REST Wizard in one of three ways:

  1. Select Junos Space > Manage REST Services from the Eclipse menu bar.
  2. Click the Manage REST Services button on the Eclipse toolbar.
  3. Select the EJB Java interface file in the Eclipse project explorer tab, right-click, then select the Create/Edit REST Services option.

The Manage REST Services screen is displayed (only in cases 1 and 2):

The REST Interface Creation screen will open.

Create REST Interface

Here you can select the EJB Source Interface and the EJB Source Implementation files, the Interface Target Context, and the Interface Target File.

If you use the Browse button to select the EJB Source Interface, the dialog will automatically find the first implementation which uses that interface. If there is more than one implementation, you can choose a different implementation by clicking on the Browse button next to EJB Source Implementation. Similarly, you can choose EJB Source Implementation first, and the dialog will automatically find the EJB Source Interface that the implementation uses.

The Manage REST Services screen is displayed (only in cases 1 and 2).

The Manage REST Services screen displays all the REST Services currently RESTified. To create a new REST Service/Interface, click the button.

The REST Interface Creation screen opens.

Create REST Interface

Here you can select the EJB Source Interface and the EJB Source Implementation files, the Interface Target Context, and the Interface Target File.

If you use the Browse button to select the EJB Source Interface, the dialog will automatically find the first implementation which uses that interface. If there is more than one implementation, you can choose a different implementation by clicking on the Browse button next to EJB Source Implementation. Similarly, you can choose EJB Source Implementation first, and the dialog will automatically find the EJB Source Interface that the implementation uses.


Configuring REST Resource

To expose an EJB interface method through the REST interface and configure REST methods, use the following steps:

  1. The following fields are displayed in the second REST Interface Creation screen:

  1. Select a method from the Methods of EJB Interface table, and click +REST (the +REST icon). In this example, the getAllCountries method is selected. The Configure REST Method window for the selected method is displayed:

  1. You can edit the fields in the Configure REST Method window as follows:
Note: The URL path is composed of: context root + service root + method name + parameters.
  1. Parameter properties can be edited in the parameters table, using in-place editors. Click on a value to activate the editor. The Method editor has two parameter tables: a general parameters table and a body parameters table. Switching the parameter category can move a parameters between the tables:

    The Following table columns can be edited:

    • Parameter Annotation drop-down—Lists the parameter annotations.
    • Path param— Path Parameters are parameters that are passed into the API as segments of the URL. For example, in the URL /api/jssdk/hello-world/world/countries/{id}, {id} is a path parameter designating the ID of a given country in the countries primary collection. Selecting Path Pram will direct the wizard to generate the @PathParam in the Java code for the REST method parameter.
    • Query Param— Query parameters are parameters that are passed into the API after the URL part of the API. These parameters are always preceded with a "?" character. Selecting Query Param will direct the wizard to generate the @QueryParam in the Java code for the REST method parameter.
    • HTTP Request Body— HTTP Request Body parameters are passed into the API through the HTTP Body or payload of the HTTP Request. Selection of this field creates the REST DTO as the envelope.
    • None—This indicates that the EJB parameter is not going to be passed into the REST method. When the EJB method is called, a default value corresponding to that parameter class is passed in (null for String and complex types, 0 for int, and true for boolean).
    • Parameter Name—This is the REST Parameter Name which is, initially, set to the name of the EJB method parameter. You can change the REST Parameter Name to be different from the EJB parameter name. Normally, you would not want to change the name of the REST parameter.
    • Is this parameter required?—Displays only for @QueryParam parameters. By default, the check box is selected. If you specify the parameter is to be required, the code generated contains a @Required attribute. This property can later be retrieved using the /api/info service. For more information, see the Rest Annotation topic.
    • Up and down buttons change parameters order.
    • Clicking Edit for simple type parameters will display the following dialog:

  1. The Method editor wizard allows editing Media Type identifiers and supported Representation Formats. The Media Type is a unique type which identifies the DTO object, configured in either the Request or Response Message Body of the Method Edit dialog.
  1. The RBAC capabilities editor is available in the respective accordion tab.

Configuring RBAC

RBAC Method Properties accordion tab allows you to configure the role-based access control (RBAC) capability for the method you are exposing through the RESTful service.

You can edit the fields in the Configure RBAC window as follows:

When finished on the Configure RBAC screen, click Next to display the Configure REST DTO screen.

Configuring Optimistic Lock Retry

When configuring a method that could potentially update a database table using Optimistic Locking (PUT, POST or DELETE methods only), you can configure an Optimistic Lock Retry and Yield Time, using the two sliders on the Configure REST DTO screen:

The Retry Count represents the number of times the EJB method will be called if the method fails with an OptimisticLockException. After this number of retry calls, if the EJB method throws another OptimisticLockException, the server will return with HTTP error code 428 (Precondition Required). If the EJB method throws any exception other than OptimisticLockException, the REST method will progress normally, meaning that it will not retry the operation but forward the exception to the appropriate exception mapper.

The Yield Time value represents the amount of time (in milliseconds) that the REST method waits before retrying another call to the EJB method.

By default, the Retry? checkbox is always selected for all PUT, POST, and DELETE methods. the Retry Count is set to 3 and the Yield Time is set to 100 ms. For PATCH HTTP methods, the Retry Count and Yield Time are equal to the value set for the corresponding PUT, POST, and DELETE methods that the PATCH method calls internally.

Configuring REST DTOs

REST DTOs are Java Beans that are serialized into an XML or JSON HTTP request or a response. After you configure your XML request or response data for your REST Web services, the Wizard creates a top-level DTO. When the generated REST services is subsequently invoked, the DTOs are serialized into the actual XML or JSON data.

You can configure a top-level DTO, by clicking on one of the Edit buttons to the right of either the Request or Response Message Body. The resulting dialog is the Configure REST DTO screen (shown below).

Note that the dialog name that appears in the dialog header will depend on which type of DTO object being configured, which is either a collection or a member of a collection.

The DTO Edit dialog displays a table, listing simple and complex fields from the EJB Model object. In this example, countries is a complex property. You can select the fields that you want to include in the REST DTO from the list.

Note: Each Top-level DTO has an unique media type that was configured in the Method Edit dialog in the previous section. This means that the same DTO can be used for GET, PUT, and POST methods (if they share the same media type). For example, a "GET /api/jssdk/countries/3" response DTO is the same as the "POST /api/jssdk/countries" request DTO. In both cases, it is the DTO associated with the media type: application/vnd.jssdk.hello-world.world.country. Therefore, when configuring the DTO for the PUT, POST, or GET method, you must select all the fields required for a GET. Deselecting a field while configuring the REST DTO in the PUT or POST method will also deselect it for the corresponding GET method as well as the PUT or POST response. If you want to exclude the field from the POST or PUT HTTP Request Body, but still want to include it in the GET response, you should configure the field as "non-required" by deselecting the "Required" check box. Go to the Make Field Non-required discussion below.

The XML Preview is displayed for the selected DTO fields in DTO Preview accordion tab:

The XML displayed in this tab depends on the following scenarios.

Scenario 1: An EJB Object is an interface or an abstract class.

Note: You must define a valid setter and getter for a given field before configuring it. The rules for a valid setter or getter are:

Scenario 2: An EJB Object has a reference to an interface or an abstract class:

Scenario 3: When an EJB object is a concrete class, but also extends any abstract class or implements any interface (except marker interfaces), or contains a reference to any one of these in the EJB Object:

Scenario 4: When an EJB Object interface extends other interfaces, or an EJB Object class extends other abstract classes that further implement interfaces:

Configuring HATEOAS Methods

The Configure REST DTO window allows you to enter details for the HATEOAS methods. For more information about HATEOAS, see the Overview of HATEOAS topic. To configure the HATEOAS method, follow these steps:

  1. Edit the fields in the Configure Method window as follows:
  2. Click OK or Cancel to return to the Configure REST DTO window.

Editing DTO fields

  1. Continue the DTO editing by selecting a complex property (country, in this example) and clicking Edit to modify the complex property in the REST DTO. The Member of Collection window is displayed.

You can edit the fields in the Member of Collection screen as follows:

    • Sortable—If this check box is selected, the @Sortable annotation is added to the getter method of this field. An app-info tag is also generated in the schema.
    • Filterable—If this check box is selected, the @Filterable annotation is added to the getter method of this field. An app-info tag is also generated in the schema.
    • Href—Any DTO can be either Object or Reference. Reference is a DTO that has an href attribute pointing to the same logical object in its primary collection (a URL that actually manages the object's life cycle). Object assumes there is either no primary collection for the DTO, or the current method is a part of the primary collection. The href value is pre-populated with the method name followed by the path parameters and key because the wizard automatically assumes that the primary collection exists based on the path.
    • URI—If the current DTO is mapped to an URI, the URI value can be edited. The REST Wizard also tries to guess 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 (not editable), and the part related to the DTO itself (can be edited).
    • DTO Preview—This section displays the XML preview for the property.
  1. Select the pull-through fields displayed and click Edit. The Configure Property window for the selected property is displayed.

    Note: You can use the Up and Down buttons to change the order of DTO and pull-through fields. Selected fields are used to form the schema. The fields without a proper getter or setter cannot be moved up or down and the option is disabled for invalid fields.

You can edit the fields in the Configure Property screen as follows:

  1. Click OK to return to the Member of Collection screen that displays configured properties.
  2. Click Finish two times to return to the method editor.

Configuring Media Type

Media Type and Format combo boxes are used to modify method media types for both Request and Response Message Bodies:

    The following are available representation formats:

  1. Click Finish to return to the resource editing wizard.
  2. Click Finish. The first version (v1) of the REST interface, the REST Implementation class, DTO classes, and DTO schemas are generated:

Configure a DTO as a Reference

To configure a DTO as a reference, select "Reference" instead of "Object" on the Configure DTO screen.

For example, this would be the case if you were configuring a method such as addStateToCountry() and you were going to specify that a reference is used to add the state, instead of the actual state itself. Similarly, you would pick "Reference" if you were configuring the method getCountry(countryId), and you were configuring the member state of the country.

Notice that the DTO field table is disabled. This is because you are configuring a POST method for adding a state reference to a country, and the POST method does not need to have any of the state fields specified because this is just a reference to a state that already exists in the primary states collection.

However, when we configure the same state_REF DTO, but for a different method getStateForCountry(int countryId, int stateId) the same fields table is not disabled. In this case, this is because even though the state returned is a reference, you might still want to configure some pull-through fields for it. (See the XML preview below.)

When configuring the media type on the last screen, note that the media type name proposal given by the wizard in the case of both addStateToCountry() and getStateForCountry() ends with state-ref and not state. This is significant because the DTOs for state and state-ref are different in that they could potentially have a different set of fields. By default, the dialog always selects only the id and name fields for the reference DTO, except for all the fields with valid getter and setter methods for the object DTO.

Configuring Reference Templates (Using Dot Notation)

In the previous section, we configured a simple template for the HREF field:


Actually, this template was already pre-configured for you by the wizard when it recognized that the DTO was a reference and a secondary collection member and set the HREF to point to the corresponding member of the primary collection of states. The wizard was also able to recognize the "id" field in the DTO as a key field for states and set the template variable to {id}.

Note: "id" is actually the name of the Java field, not the corresponding XML name. In this case, they happen to be the same, but you may want to have a more complicated name for the key, so you need to remember to use the Java name, not the XML name.

Sometimes the wizard may not be able to select the correct template and will need some help from you. This happens when the DTO does not have a field called "id" or does not have the "id" as part of the field name. Also, there could be many fields with "id" in the name, and the wizard may not know which one to pick as the key. You may also want to use "name" (although, that is not recommended) or some other field as the key field. In all of these instances, you need to specify your own key field.

As you fill in the key field's name in the template, you will notice that the wizard automatically selects that field in the DTO, if it was not already selected prior to you filling in the field's name. This is necessary because the field needs to be present in both the input and the output of REST methods. When the template is used as an output body, the REST infrastructure code on the server will fill in the template with the value of the key field and generate the correct HREF value. On input, if the HREF is specified by the user as an attribute of a reference, the HREF will be parsed according to the template, and the field's value will be filled in by the REST infrastructure code.

In this example, you specified the "id" field of the current DTO. However, the key field may not be part of the current DTO at all. The key field can be contained in a child or a contained DTO. In that case, the wizard will allow you to specify the key field in the template, using the Dot Notation. For example you can specify:


This would be the case if the ID was actually not part of the current State object, but contained inside the stateInfo object's stateId field. Notice that for both variables, the actual Java object names are used, not the Java class names.

Let's say we had a link called country which we wanted to use inside a state object. Note the hierarchy of the current State DTO:


In this case, we can use the Dot Notation to specify the key as follows:


The first "_parent" would take us back to the states level, the second "_parent" would take us to the country level, and we will find the country ID there. Notice how the Dot Notation is a path specification for the current DTO hierarchy and not for the actual template hierarchy.

The Dot Notation can be used anywhere where you can specify a template, such as in URIs, HREFs, and method links.

Configure a Heterogeneous DTO as a Reference

The Heterogenous secondary collection is a collection of DTOs or objects, where each member DTO is a reference to a primary collection object. For example, if in the HelloWorld application, State class has two descendant classes: EvenState and OddState, and there are two primary collections (one for EvenState and another for OddState), then any secondary collection of State might be treated as heterogeneous.

The REST Wizard detects potential heterogeneous secondary collections automatically when a base class is used for a Model Object. In such a case, an "Heterogeneous?" check box appears on the secondary collection DTO page in the Object/Reference section.

If the "Heterogeneous?" check box is disabled, the secondary collection of State will be treated as a regular (homogeneous) collection. Enabling the check box makes the Href textbox disabled. In this case, the "Edit Hrefs" button appears, allowing the user to edit multiple href values, one for each descendant class:

As a result, each State inside Country has the href value generated based on its actual class: EvenState or OddState:

Only base class (superclass) properties are supported as pull-through fields. Any additional properties, which are declared in descendant classes, are ignored. So for the EvenState/OddState example, only base State class properties (id and name) are included in the response XML.

Note that the base class source code does not need to be part of the application. It can be derived using a Java class file that is placed in a shared jar file. This way multiple apps can share a base class that is exposed by a single app or the platform.

If the DTO is a single class DTO with no base class, you can still enable a heterogeneous configuration by selecting the "Heterogeneous?" checkbox. In this case, the wizard cannot find the href templates for the heterogeneous collection, and the application code needs to supply the href and type values at run time. This can be done by creating two additional fields in the EJB Model Object: link and type. These fields are XML Transient and are annotated with the @XmlAttribute annotation.

@XmlAttribute(name = "href", required = false)
protected String link;
@XmlAttribute(name = "type", required = false)
protected String type;

In addition, when the MO object is accessed with a REST call, it is the responsibility of the EJB to set these two fields with their corresponding href and type values. In this way, this mechanism allows each app to set these attributes dynamically. Note that these fields do not need to be persisted in the database or be part of any entity object. They are there to return href and type values back to the REST method. The wizard generated code will get these values and set the corresponding attributes in the response.

Also note that a heterogeneous link does not need to be part of a collection. You can have a single reference anywhere in your XML or JSON body, and it can be either a homogeneous or a heterogeneous reference. The wizard will allow you to configure a heterogeneous reference every time you check the "Reference" checkbox.

Shared DTOs

Top-level DTO can be shared for method request and response as well as between several methods (for example, in CRUD methods). A shared DTO means that the same DTO Java class is used as parameters in different methods, so any changes to the DTO in one method affects it in another method.

For example, in the addCountry() method in the HelloWorld example, the request and return Country DTO is shared, and the changing request Country DTO will also affect it for the response. The Country DTOs for CRUD methods getCountry(), addCountry(), and updateCountry() are also shared.

The base rule for DTO sharing is simple: if two DTOs have the same media type by default (on initial EJB RESTification), those DTOs are shared. Note that this means that if you change the media type name from its default name, this will not force the Wizard to create a new DTO Java bean. It will only change the media type designation of the DTO, but the DTO will still be shared with other DTOs in the other CRUD methods.

While being effectively the same Java class, shared DTOs behave a bit differently for request and response. The request DTO editor has an additional column for the Required DTO property:

All properties checked in the left column will be included in a Java class, and thus transferred to or from the client on a REST method envocation. But non-required properties can be omitted when transferring the object from the client to the server with a POST or PUT request. In the example above, the id property of Country< will be returned by the GET request on a country, but the user can omit the id property when PUTing or POSTing a country.

Single-Getter and Relative DTOs

A single-getter DTO is a DTO that is returned by a GET method, which fetches a single object (for example, GET /countries/12345). Every single-getter DTO is a top-level DTO. When a single-getter DTO is configured in the Wizard, and the configuration is saved, some of the properties of this DTO are copied to its relative DTOs. Relative DTOs are DTOs that are built from the same source EJB Modeled Object. Both collection and reference DTOs are relative DTOs. For example, the DTOs States.State, Country.States.State, and State_REF are all relatives of the State DTO.

The properties that are copied from the single-getter DTO to the relative DTOs are:

Note that although the user can override these properties in the relative DTO, there is no reason to do that because these properties would just be overwritten again when the single-getter DTO is modified.

Therefore, it is highly recommended that the only configurations that the user should change on the relative DTOs are:

In fact, the wizard will not allow the user to modify most of these single-getter DTO properties in relative DTOs.

All the other DTO properties should be configured in the single-getter DTO only.