Tuesday Apr 21, 2015

Working with variables in the REST Service Editor

Working with Variables in the REST Service Editor

 By Preston Appel

This blog continues surveying the REST Service Editor's ability to explore an existing REST API and to describe that API. Here we look at how variables are used in the address of a request on the REST Client page. We'll also see how this is modeled on the REST API page. Finally, we’ll see how variables are translated to code with the artifact generation capability of the editor.

This blog continues work that is described in the blogs Introduction to the REST Service Editor, Part 1 and Introduction to the REST Service Editor: Generation, Part 2. We recommend reviewing these blogs before proceeding if you’re not familiar with the REST Service Editor.

Our Description of the REST API and Data Types

This blog builds on our description of the REST API and Data Types that we've compiled through the course of several blogs. To get up to speed, here is the REST API we’ve described so far, which is expressed as a tree of paths with their associated requests. The root path is "http://localhost:4545." We'll alter its child path "departments" by adding a child path and a request.
REST API model from previous work

We'll also be using the Department data type that we previously imported.
Data Types from previous work

With that background, let's introduce a variable.

Exploring a REST API Using Variables

On the REST Client page, this version of the REST Service Editor supports variables for the address URI. These variables take the form of {variable-name}. In the exposed REST API that we're exploring, we can request a single department with a URI like "http://localhost:4545/departments/dep2." In this case "dep2" indicates that we'll return the department with an id of 2. Here we'll use a variable for the id: "http://localhost:4545/departments/dep{id}." There's nothing special about the variable name we've used. We could just as easily have written "dep{identifier}." In other words, it doesn't have to match the name of the attribute of the department payload.
Address URI with variable

Now, the curly brace characters are not legal in a URI. On the REST Client page, when we send the request, the variable (including its curly braces) will be replaced by an actual value. However, while typing the variable, you will see that the curly braces cause a validation error—but only when you have only one of the curly braces. The validation recognizes when we have valid variable syntax.
Validation of illegal characters in the Address URI

We'll restore the address to "http://localhost:4545/departments/dep{id}" and click the Send Request button to see how the variable substitution occurs.
Send the request with a variable

We enter the value for the id variable in the Replace Variables dialog. If we had other variables in the address, they would also appear in this dialog.
Replace Variables dialog

Here we can see that the response contains the department with id 2.
Response returning department 2

Now let's import the REST Client information to get the path with this variable into our description.

Importing a Variable

Click on the Import the REST Client Information button to start the process.
Import the REST Client Information button

This brings up the Import REST Client Information dialog. We don't really need to import the data types because we have them from previous work we did on the description. However, to illustrate that we are working with the same data types, we'll leave this checked.
Import REST Client Information dialog

On clicking the Next button, we enter the name of our request "getDepartment." We also see that we've already imported the "http://localhost:4545" and "departments" segments as paths in our tree, so we just need to import the final segment "dep{id}."
Import Request page of dialog

Clicking the Next button again, we confirm that we already have the data types we need. We'll leave "Merge types into the existing matching domain types" checked to use our existing data types. See the Introduction to the REST Service Editor, Part 1 blog for details on how we imported the Department and Employee data types.

A few words are in order about the names of the data types. The Dep data type name comes from the last segment in the address, dep{id} with {id} dropped. The Employees1 data type name comes from the name of the employees array in the response; it is disambiguated from the existing Employees data type by adding 1 to the end. This is also covered in the Introduction to the REST Service Editor, Part 1 blog.

After we click the Finish button, we are taken to the REST API page that shows our new "getDepartment" request. It has been added under the new "dep{id}" path that was added to our tree of paths.
REST API model with new path and request

At this point we'll generate artifacts for our REST API description.

Note: Currently, the REST Service Editor does not support setting the type of the variable in the path segment. So, for example, we can't specify that the {id} in the dep{id} path is an Integer. There is more on this in the generation section below.

Artifact Generation and Variables

After saving, we click the Artifact Generation button to generate Java 8 code for our request.
Artifact Generation button

We won't go through the screens of the Artifact Generation wizard here. Instead, please refer to the Introduction to the REST Service Editor: Generation, Part 2 blog for the details. The code below shows the call on the RESTService class to get the department. Note that an id must be passed to the method.

Note: Since in the REST API model we do not yet support specifying the type of the variable in a path segment, the id parameter in the getDepartment method is generated as an Object. This becomes an issue if this code is to be used in a data control to bind to the UI. If that is the case, subclass the RESTService class (so that future regenerations of code will not replace your change) and overload the getDepartment method to take an Integer type for the id parameter.

package mobile.model.service.localConnection;

import mobile.model.datatype.DepartmentObject;

import mobile.model.restapi.LocalClientContextFactory;
import mobile.model.restapi.PathFactory;

import oracle.eclipse.tools.rest.runtime.client.ClientContext;

/**
 * Service class generated to expose requests defined on the REST Service file:
 * /ViewContent/restServiceEditorDemo.xmi (last modified: 2015-03-11 12:27:11.643)
 */
public class RESTService {
  public DepartmentObject getDepartment(Object id) throws Exception {
    try (ClientContext context = LocalClientContextFactory.INSTANCE.create(ServiceUtil.CONNECTION_NAME)) {
      return PathFactory.INSTANCE.createLocalConnectionPath(context).path(context.getConnectionPath())
        .getDepartmentsPath()
        .getDepidPath(id)
        .invoke()
        .getDepartment();
    }
  }
}

To conclude, here's the class generated for the new path: mobile.model.restapi.localConnection.departments.DepidPath. (For the sake of space, the package and imports are not shown.)

/**
 * Interface generated for the 'dep{id}' path defined on the REST Service file:
 * /ViewContent/restServiceEditorDemo.xmi (last modified: 2015-03-11 12:27:11.643)
 */
@PathValue(value="dep{id}", parameters="id")
public interface DepidPath extends PathObject {
  @RequestAccessor
  public static interface Request {
    @Action(HTTPMethod.GET)
    @Header(name="Accept", value="application/json")
    @Output(representations=@Representation(type=DepartmentObject.class))
    DepartmentObject getDepartment() throws RequestException;
  }
  
  @Override
  DepartmentsPath parent();

  /**
   * @return creates a new object that exposes the requests
   *         defined for this path
   */
  Request invoke();
}

Tuesday Apr 14, 2015

Working with secure REST Services: Basic Authentication

Working with secure REST Services: Basic Authentication

By Preston Appel

The REST Service Editor's REST Client page allows users to experiment with existing REST APIs. The blog Introduction to the REST Service Editor, Part 1 provides an example of sending a simple GET request to a server and storing a description of the request and of the received payload. That example did not require any authentication. This blog expands on that case by describing how to set up HTTP authentication to explore REST APIs that require this type of authentication. A later blog will cover OAuth 2 authentication.

Let's look at this case of a resource that requires authentication. If we enter the address of this resource and click the Send Request button, we receive back a response with status 401 Unauthorized. Note that throughout this blog, I've obscured the address URI since it is not publically available.
REST Service Editor's REST Client page showing Unauthorized response

At this point, the user will need to look up what authentication is required for the REST API they are accessing. Once this information is known, authentication is set up by clicking the Set Authentication Information button. The blue circle on the button indicates that no authentication information has been entered yet.
REST Client page's Set Authentication Information button

Clicking the button pops up the Authentication Information wizard and we select HTTP (basic, digest, universal) for our type of authentication.
Authentication Information dialog's authentication type page

Clicking the Next button, we can now enter the username and password.
Authentication Information dialog's HTTP page for username and password

Now, when we look at the Set Authentication Information button, we don't see the blue circle, indicating that we have entered the authentication information. The tooltip shows the type of authentication that was set.
Set Authentication Information button showing authentication entered

One point of clarification: the fact that the blue circle has disappeared from the Set Authentication Information button does not indicate that the authentication information is valid, only that the required fields for the particular authentication type have been entered.

The REST Service Editor fully supports undo and redo, so it is easy to reverse what we've just done. We can also click the Set Authentication Information button again and select None for the authentication type (and then click the Finish button).

Now when we click the Send Request button, we see that our request was properly validated and we now have a valid response.
REST Client page showing successfully authorized response

Remember that the REST Client page is not part of the persistent state of the REST Service Editor, so the authentication information is not saved. This authentication mechanism is provided so that a user can explore a REST API that requires authentication (and then optionally store a description of the request and of the received payload.)

Friday Apr 10, 2015

OEPE 12.1.3.5 brings new tools for Storage Cloud Service and MAF 2.1.1

Oracle Enterprise Pack for Eclipse (OEPE) 12.1.3.5 is now available from the Oracle Technology Network and includes new tools for Oracle Cloud services and Oracle MAF.

New Tools for Oracle Storage Cloud Service


Oracle Storage Cloud Service is a secure, elastic, and on-demand cloud based storage solution. Customers with Storage Cloud Service accounts will be able to interact with their service instances from within OEPE 12.1.3.5 through the Oracle Cloud view. The Storage Cloud Service design time tools support a number of actions including:
  • Create new storage containers.
  • Store and retrieve objects in the storage containers.
  • Rename the storage object and manifest object.
  • Update the container and object metadata.
  • Support transparent encryption and define access controls to containers.
  • View the properties of any container and object.

Support for Oracle Mobile Application Framework 2.1.1


OEPE MAF design-time and runtime tools have been updated to support Oracle MAF 2.1.1. All existing mobile development tools have been updated to support the new Oracle MAF release while still continuing to support past Oracle MAF versions.

New MAF 2.1.1 runtime features include:

Local Notification support - MAF 2.1.1 provides support for scheduling, cancelling and receiving local notifications via the Device Feature Data Control, as well as Java and JavaScript APIs.

Support for completely disabling logging -  MAF 2.1.1 provides support for completely disabling all logging from a MAF app. To force this behavior, add the following to the app's adf-config.xml.

Wednesday Mar 18, 2015

REST Service Editor Query Parameters

REST Service Editor Query Parameters

By Preston Appel

This blog covers how to specify query parameters using the REST Service Editor. As you will see, it is possible to set the scope of the query parameters to every request of a given URI or to just a single request. We will also review how to modify the output representation to only contain certain attributes. (This is also covered in the Modeling a POST Request and Redirection in the REST Service Editor blog.)

Background of Our REST API Model

In previous blogs (Introduction to the REST Service Editor, Part 1 and Modeling a POST Request and Redirection in the REST Service Editor), we described a REST API that had been exposed by an application. This is shown below on the REST API page of the REST Service Editor.
REST Service Editor's REST API page showing model

Based on the documentation of the existing REST API that we are describing, we know that we can pass the query "verbose=false" to our GET request for departments. In this case, the response's JSON payload will just contain a summary description of each department. Usually, when we send a GET request to "http://localhost:4545/deparments," it returns multiple departments, where each department has an id, name, optional manager and an array of employees. When the query "verbose=false" is added to that URI, the JSON payload in the response will just contain the id and name of the department. How might we model this?

Modeling a Query on the Path

Let's say that we want to model this by adding the query to the "departments" path. (In this case, we don't actually want to do this, but we’ll get to that in a moment.) First, remember that the "departments" path is a child of the root path "http://localhost:4545." Since the paths will be combined into the address "http://localhost:4545/departments," we are just altering the address to include a query. We could just type the query at the end of the "departments" path, but to ensure we have the correct syntax (and to encode any illegal characters), we will use the Compose Address button to do this work.
REST API page's Compose Address button

Upon clicking the Compose Address button, we'll add the query "verbose=false" to the departments path.
Compose Address dialog

We have now altered the "departments" path to contain the query.
Altered departments path with query

Now, if we had a case where the query should apply to all the requests under the path, then we could model it this way. However, we don't want the query "verbose=false" to apply to our "createDepartment" request. To see that it applies to all requests—even those we don’t want affected—select "(POST) createDepartment" and look at the status line at the bottom of OEPE. The status line indicates the address that will be used for the request.
Status line showing address

Let's back out this change. We can either type control-Z, or click Edit/Undo Set 'Value.'
Edit/Undo Set 'Value' menu pick

Modeling Query Parameters on a Request

At this point, we'll create a new request "getDeptSummaries" on which we'll set a query parameter. To do so, we'll right-click on the Requests folder under the "departments" path and select New/Request.
Create new request from context menu

Enter "getDeptSummaries" in the Name field of the request (leave the Method as GET). We also enter the HTTP Header "Accept=application/json" but I haven’t shown this step. See Modeling a POST Request and Redirection in the REST Service Editor, if you need help with this. It's very similar to how we'll add a query parameter. To add "verbose=false," click the Add button on the Query Parameter tab of the Request.
New request named getDeptSummaries

Enter the name and value in the Add Query Parameter dialog.
Add Query Parameter dialog

We've now set up the query parameter for the request.
verbose=false query parameter

At this point, we can easily see what address will be used for each request. With "(GET) getDeptSummaries" selected in the Outline on the REST API page, the status line is "Address: http://localhost:4545/departments?verbose=false."
status line showing address for getDeptSummaries

With "(GET) getDepartments" selected in the Outline, the status line is simply "Address: http://localhost:4545/departments."
status line showing address for getDeptments

Now, it just remains to set up the output.

Being Precise About Output

For our "getDeptSummaries" request, we want to model that the response will only contain a summary of the information from the departments. To set this up, we click on the Request's Output tab and select Representation for the Type field. This is so we can specify the Output that will be returned in the response.
Output representation

Click the Add button to set up the Representation. In this case, we will be returning Department objects, so we select this for the Data Type. Since there will be more than one department, we check the Multiple box. Finally, since our documentation tells us that the query parameter "verbose=false" will result in returning just a summary of the department information—specifically, the id and name attributes for each department—we uncheck All attributes and select the id and name attributes.
Add Representation dialog

We now have described our "getDeptSummaries" request with some precision.
REST API page showing final model

With this model we can now, for example, generate Java 8 code, which will allow us to programmatically send our "getDeptSummaries" request. The generated code will know how to return just the department summaries due to how we modeled the output representation.

Additional Information

Oracle Enterprise Pack for Eclipse OTN Page

Oracle MAF OTN Page

Oracle MAF on YouTube 

Tuesday Mar 10, 2015

Modeling a POST Request and Redirection in the REST Service Editor

Modeling a POST Request and Redirection in the REST Service Editor

 By Preston Appel

In the blog Introduction to the REST Service Editor, Part 1, we sent a simple GET request to a server and then stored a description of that request and of the JSON payload we received back as a response. This blog is a continuation of that work, but we will be focusing on the REST API page of the editor as we model a POST request to create a department. This POST request involves redirection in that upon sending the request, we receive back a location that is the URI of the newly created department. We'll also see how to test the POST request that we’ve modeled by using the Copy to REST Client functionality.

Getting Up To Speed

To better understand the POST Request, below is a reminder of the description of the request and data types from the Introduction to the REST Service Editor, Part 1 blog. First, the REST Client page shows our "getDepartment" request. It has an HTTP Header: "Accept=application/json" (not pictured), and its Output Representation is a Departments data type.
REST Service Editor's REST API page with original model

The Data Types page shows the top-level Departments data type that we created, which contains multiple instances of the Department data type.
REST Service Editor's Data Types page with original model

We'll create a new request on the REST Client page and use the Department data type in our Output Redirection Representation.

Describing a New POST Request

This blog assumes that we have documentation on the existing REST API that we are describing in the REST Service Editor. Based on that documentation, we will be modeling a POST request to create a new department on the server.

If we were using the REST Client page to send a POST request to the application exposing the REST API, we would use the address "http://localhost:4545/departments." On the REST API page, that address has already been set up with a tree of paths. The root path "http://localhost:4545" has a child path "departments" with a Requests folder. That is where the existing "getDepartments" request was imported. By right-clicking on that Requests folder we can create our new request.
REST API page creating new request

We now set the Method field to POST and type "createDepartment" in the Name field.
REST API page showing new POST request

Based on the documentation of the existing REST API, we know that to create a department on the server, the POST request must have content that is expressed as a JSON payload. We can meet the JSON requirement by adding an HTTP Header "Content-Type=application/json" to the modeled request. To do so we click the Add button and enter the data.
Add Header dialog
HTTP Header created

We now need to model the input of our POST request. After clicking the Input tab of the Request, we select Representation for the Type because we want to send a Department data type for our POST request.
Input Representation creation

We select the Add button and select Department in the Add Representation dialog. By default "All attributes" is checked.
Add Representation dialog

But based on the API's documentation, we cannot send the "id" attribute to the server when creating a new department. Moreover, that documentation for this functionality tells us that we only need to send the "name" attribute to create a new department. So in the dialog we will uncheck "All attributes" and check the "name" attribute.
Add Representation dialog altering attributes

We have now partially described our "createDepartment" request.
Department Input Representation created

Testing the POST Request

We still have to do some work to describe the redirection, but for now, we will test what we have. With "(POST) createDepartment" selected in the Outline of the REST API page, click the Copy to REST Client button for the request.
Copy to REST Client button

This takes us to the REST Client page where we can see that the Method, Address and Headers contain what we have modeled. If, however, we click on the Input tab in the Request Details section, we don't see the Representation we set up. In fact, we only see the option to select a Body type.
REST Client page Input Type

For the current version of the REST Service Editor, the REST Client page only supports an Input of Body. To test our request then, we'll have to do a little more work. Select the Body type and enter {"name":"demo department"} for the value of the body.
REST Client page Body Input Type

Click the Send Request button. The Response section of the REST Client page shows a status of 201 Created, and the Headers section has a Location set to "http://localhost:4545/departments/dep5." This redirection URI allows us to send a GET request for the newly created department.
REST Client page Response

We can either click the arrow button to set the address to the response redirected location or control-click the arrow to send a GET request to the redirected location immediately.
REST Client page Response Status

Here are the results for control-clicking the arrow.
REST Client page redirection URI Response

Describing the Redirection for Our New POST Request

We now return to the REST API page to complete our modeling. With "(POST) createDepartment" selected in the Outline of the REST API page, click on the Output for the Request. Here we select Redirection to describe the behavior that we just demonstrated on the REST Client page.
REST API page Output Redirection

Add "Accept=application/json" to the Headers.
REST API page Output Headers

Add Department to the Representation. Leave "All attributes" checked.
Add Representation dialog

After saving, here's the model we've created of the "createDepartments" POST request.
REST API page showing final model

We now have a model that can, for example, be used to generate Java 8 code. This code will allow us to programmatically send a POST request to create a department and also to process the redirection by sending a GET request to retrieve that new department.

Additional Information

Oracle Enterprise Pack for Eclipse OTN Page

Oracle MAF OTN Page

Oracle MAF on YouTube 

Monday Mar 09, 2015

Oracle at EclipseCon 2015

Its beginning to look a lot like EclipseCon, everywhere you go.

 EclipseCon 2015 is back in the Bay Area and, once again,  Oracle is a Gold Sponsor.

 If you are attending EclipseCon this year, come by the Oracle Booth #18 and say "Hi!". Throughout the week, you will have the opportunity to see demos and chat with team members from Mobile Application Framework, Java, OEPE, Oracle Cloud, and Hudson.

Don't forget to checkout our sessions this week as well


 Date  Title  Speaker  Location
March 10 2015 @ 3:00-3:35PM
iOS Development with Eclipse and Java - Yes it is possible!
Shay Shmeltzer
Sandpebble AB
March 11 2015 @ 7:30-8:30PM
Eclipse and Cloud Hosted Development Platform
Greg Stachnick
Sandpebble AB
March 12 2015 @ 9:00-10:00AM
Keynote: Java 9 and Beyond
Mark Reinhold
Grand Peninsula DEFG

Sunday Mar 08, 2015

Mobile Feature Archive Import and Export with OEPE

Mobile Feature Archive Import and Export with OEPE

By Ian Trimble

Each Mobile Application Framework (MAF) application's view project can be exported as a Mobile Feature Archive (FAR), which can subsequently be imported into other MAF applications.

A Mobile Feature Archive contains all of a view project's artifacts, including features, AMX and HTML pages, and task flows. It also contains information about connections and Cordova plugins, which is application-level information that is exported with a FAR so that the correct application-level information can be merged on FAR import. This application-level information is critical to allowing imported features to work correctly.

Export

To begin export, select File > Export... from the menubar, or right-click in the Project Explorer or on a view project and select Export...

In the Export dialog, select Oracle > Mobile Application Framework > Mobile Feature Archive (FAR), then select Next >
Export dialog

On the Export Mobile Feature Archive (FAR) page, enter or browse for a view project (only view projects are valid for FAR export) and enter or browse for a FAR (this must be a legal pathname for the desired FAR, which has a ".jar" extension.) Select whether or not to include connection details. Create FAR by selecting Finish.
Note: if export was started by right-clicking on a valid view project, it will be pre-populated.
Export Mobile Feature Archive (FAR) page

Import

Importing a FAR is performed in the MAF Application Editor, which can be opened by expanding an assembly project in the Project Explorer and double-clicking MAF Application Editor under the MAF node.

In the MAF Application Editor, there are two ways to begin the import of a Feature Archive:

    1. Right-click the Feature Archives node and select New > Feature Archive. Adding FAR in MAF Application Editor
    2. At the top-right of the MAF Application Editor, select Browse next to the URI field.
    3. Enter or browse for the desired FAR, then select OK. Browse for FAR URI in MAF Application Editor
  1. Drag and drop a FAR from the file-system onto the Feature Archives node.

Importing Connections

To import connections that were defined in the FAR, select the Connections node under the Feature Archive in the MAF Application Editor. Select FAR connections in MAF Application Editor

Connections can be in several different states, both immediately after import and after user actions to decide how to treat each connection. The states are as follows:

  • New: the connection is not already defined in the application and is available for import.
  • Conflicting: there is a conflict between the connection and a connection that is already defined in the application; manual user action will be required to resolve the conflict. The first step in resolving the conflict will be to look at the this connection and the application's connection, to decide how the application's connection could be adjusted to allow import of the connection in the FAR.
  • Partial: the connection is incomplete; manual configuration will be required to make it valid.
  • Not Valid: the connection is somehow invalid; a connection in this state will likely require consultation with the author of the FAR to correct.
  • Equivalent: the connection is equivalent to a connection already defined in the application; import is not necessary.
  • Ignored: the connection has been marked as ignored, usually because it has been determined that the connection is not necessary or that the connection is not valid and so a valid connection has been defined in the application directly.

Select a connection in the list on the right, then select the Import (Import">) button to the right of the list. The connection will now be shown as equivalent, since a corresponding connection has been created in the consuming MAF application. Imported connection in MAF Application Editor
Note: you can also select the Ignore (Ignore) button to the right of the connections list if you choose not to import a connection; this could, however, prevent features in the imported FAR from functioning correctly.

Importing Plug-ins

To import Cordova plugins that were defined in the FAR, select the Plug-ins node under the Feature Archive in the MAF Application Editor. Select FAR Plug-ins in MAF Application Editor

Plugins can be in several different states, both immediately after import and after user actions to decide how to treat each plugin. The states are as follows:

  • New: the plugin is not already defined in the application and is available for import.
  • Equivalent: the plugin is equivalent to a plugin already defined in the application; import is not necessary.
  • Ignored: the plugin has been marked as ignored, usually because it has been determined that the plugin is not necessary or that the plugin is not valid and so a valid plugin has been defined in the application directly.

Select a plugin in the list on the right, then select the Import (Import) button to the right of the list. If this is a new plugin, you must select a URI that points to the equivalent Cordova plugin, since plugin source is not stored in a FAR (only its registration and usage information is stored). The plugin will now be shown as equivalent, since a corresponding plugin registration has been created in the consuming MAF application. Imported plug-in in MAF Application Editor
Note: you can also select the Ignore (Ignore) button to the right of the plugin list if you choose not to import a plugin; this could, however, prevent features in the imported FAR from functioning correctly.

Registering Features

To register features that were defined in the FAR, select the Registered Features node in the MAF Application Editor. Select Registered Features in MAF Application Editor

Select the Browse (Browse) button to the right of the list, then select a feature and click OK. Select feature in dialog

After registering a feature, you may notice that the Plug-in Enablement node shows a warning. This indicates that a registered feature uses a plugin that has not been enabled for use by the application. To remedy this, select the Plug-in Enablement node in the MAF Application Editor. Enable plugins in MAF Application Editor

Select the Enable All button (Enable All) to the right of the list. This will enable all required plugins.
Note: you can also enable individual plugins by selecting the Browse (Browse) button to the right of the list and selecting plugins that you wish to enable. Not enabling plugins could prevent features from functioning correctly.

Additional Information

Oracle Enterprise Pack for Eclipse OTN Page

Oracle MAF OTN Page

Oracle MAF on YouTube 

Saturday Mar 07, 2015

Continuous Integration for MAF using OEPE and Hudson

Continuous Integration for MAF using OEPE and Hudson

By Cameron Bateman

Audience

This article is intended for senior development or release engineers who want to put their MAF development effort into a standard “continuous integration build cycle. This article will focus on using Git and Hudson to achieve this, although the basic concepts are applicable to other systems.

Helpful Things to Know

The OEPE MAF build system is based on Ant. We will provide all of the ant script fragments you need to accomplish the goals of this article, but for debugging purpose it will useful if you already understand know the basics.

This article also makes use of OEPE (Eclipse), Hudson, Git and a system shell prompt. Having a basic understanding of how to install and use these systems is required and not all steps will be given in these areas because instructions can be found elsewhere.

Things to Install First

To start, download and install the following:

Apache Ant – make sure this is on your path.

Git (http://git-scm.com/downloads) – you will only need the command line client; we will use the GUI client that comes with OEPE.

Hudson (http://hudson-ci.org/) – for this article it is sufficient to download the hudson.war and use it in standalone mode.

Android SDK (http://developer.android.com/sdk/index.html) – scroll to the bottom to "Other Download Options" and you just download the basic SDK without an IDE. Follow Android instruction as to how to update the SDK and create and AVD you wish to deploy to the Android emulator; having an Android device is recommended but not required because your application will generally deploy faster.

Oracle Enterprise Pack for Eclipse

Create an Android SDK Configuration in OEPE

Before creating a MAF application, it will be helpful to define an SDK configuration in OEPE. An SDK configuration is used to tell OEPE what version of a mobile SDK you want to use and where all its platform-specific tools reside.

To create a new SDK configuration got to Preferences (from the the Eclipse menu on Mac, from the Windows menu on other platforms) type "Android"

Click Add... to open the new SDK dialog. Use the file selector (...) to navigate to the directory with your sdk in it. This is the directory that contains (among others things) the "platforms" and "platform-tools" folders.

Click OK. The preference page should now populate with information about the SDK. Click OK on the dialog to save the changes.

Create the App and Test It From OEPE

For this article, we will use the sample application HelloWorld. To create a new instance of the application, select File->New->Examples...

In the wizard, select the MAF Examples wizard.

Click "Next >". In the selection page, pick "Hello World" and leave the runtime version as the default (MAF 2.1).

Click "Next >". A default deployment target should be created based on the SDK configuration you created above. Hit Finish.

The application will now be created as three Eclipse projects. You may be prompted to switch perspectives. Answer "Yes". At the end of the creation process your OEPE workbench should look like something like this:

We now have a pre-created, working application in our workspace. We can test it out by deploying it to an Android device or emulator. Before proceeding, ensure that your emulator is running or that your device is correctly connected to your PC by USB. Refer to Android SDK documentation for more details.

Now lets test the application from OEPE to make sure it works.

Testing the Application From OEPE

Once you have your Android device or emulator running, you can proceed to deploy your application by clicking on the "Debug" toolbar dropdown.

Select the "Debug Configurations..." item to open the launch dialog. Find the "MAF Application" item in the configuration list and double-click it (or click the "New launch configuration" menu item near the top-left) to create a new configuration.

Click on "Debug" at the bottom right of the dialog. After the initial launch sequence dialog completes, your console should open with the output from the build's progress. Depending on your system and the speed of your device, this may take a few minutes.

When it finishes you should see the application launched in your device/emulator.

Modifying Your App For CLI Use

To make your project ready for command-line building, you will need to modify the build scripts a little bit. The target generates some defaults that we need to update.

First, you need to change the workspace filtering in the explorer so that you can see the files.

The targets are created in directories with names starting with a ".", which makes them hidden by default. To disable the filtering, click on the Project Explorer preferences menu.

Uncheck the checkbox for ".* resource" and click OK.

You should now be able to see the folder in your "HelloWorld" project. It will be called something like ".main.android". Expand this folder and the "profile" folder below it. Each sub-folder of the profile folder acts as a named configuration for the MAF build. For non-ide builds, the application wizard creates a template profile called "headless". To create your own profile, copy and paste this folder under profile to a new one called "releng" (the name is arbitrary but we will use releng here).

Now we need to modify the copy of "configure-fars-override.xml" under the new releng directory so that the build will know where the application artifacts are when running outside Eclipse.

Open "releng/configure-fars-override.xml" and find the target named "configure-override-projects".

The top of the target will look something like this:

<target name="configure-override-projects">
    <property name="oepe.adfmf.assembly.project.dir.0" value="/Users/cbateman/cbateman-mac-1/oepe-product-test/workspaces/product.oepe-maf-21_ws2/HelloWorld" />
    <property name="oepe.adfmf.assembly.project.dir.1" value="/Users/cbateman/cbateman-mac-1/oepe-product-test/workspaces/product.oepe-maf-21_ws2/HelloWorldApplication" />
    <property name="oepe.adfmf.assembly.project.dir.2" value="/Users/cbateman/cbateman-mac-1/oepe-product-test/workspaces/product.oepe-maf-21_ws2/HelloWorldView" />

We need to update those three properties to make them independent of the Eclipse workspace. First, we add two lines of ant script that allow us to pass in the absolute path of the application in from the command-line.

<property environment="env" />
<fail unless="env.WORKSPACE" message="env.WORKSPACE must point to the workspace" />

Then update the paths in the original properties.

<property name="oepe.adfmf.assembly.project.dir.0" value="${env.WORKSPACE}/HelloWorld" />
<property name="oepe.adfmf.assembly.project.dir.1" value="${env.WORKSPACE}/HelloWorldApplication" />
<property name="oepe.adfmf.assembly.project.dir.2" value="${env.WORKSPACE}/HelloWorldView" />
The first lines of the target should now look like this:
<target name="configure-override-projects">
  <property environment="env" />
  <fail unless="env.WORKSPACE" message="env.WORKSPACE must point to the workspace" />

  <property name="oepe.adfmf.assembly.project.dir.0" value="${env.WORKSPACE}/HelloWorld" />
  <property name="oepe.adfmf.assembly.project.dir.1" value="${env.WORKSPACE}/HelloWorldApplication" />
  <property name="oepe.adfmf.assembly.project.dir.2" value="${env.WORKSPACE}/HelloWorldView" />

Save the file and close.

The last thing to do is to add an entry in releng/build.properties. To make it easier to test the command-line build, we will tell it to automatically generate a debug self-sign keystore for Android. Add this key-value pair:

oepe.adfmf.build.autogen.keystore=true

Creating A Local Repo and Committing Your App

In order to test your application in a "pure" CLI context, it's a good idea to test a different copy of the application than the one in the IDE. To do this, we will create a local GIT repository to simulate a real CI scenario where a developer has written an application and checked it in for use by Hudson or other build containers.

To add your application to a new local repository, click on one of the projects in the Project Explorer and hit Ctrl-A (Cmd-A on Mac) to select all. Right-click and select Team->Share Project...

In the Share Project dialog page, click on "Git" and hit Next. In the Git configuration dialog, click "Create..." and enter a local path on your disk.

Click Finish. Click Finish again to complete the wizard. When the wizard completes, you will see that all your project artifacts have been marked with "?" decorations and ">" characters in the Project Explorer to indicate that they need to be committed to Git.

To commit the changes, switch to the Git perspective (hit Ctrl-3 or Cmd-3 and in the search box type "Perspectives Git" then click on the selection). In the left-hand "Git Repositories" view, click on the repository you just created. At the bottom of the perspective, switch to the "Git Staging" view. Now, click one of the files in the "Unstaged Changes" list and hit Ctrl-A (Cmd-A on Mac) to select all. Right-click on the selection and click on "Add to Index" in the menu. All of the files listed under "Unstaged Changes" should move to the list below titled "Staged Changes".

Now, type a comment in the "Commit Message" box and press "Commit".

If you switch back to the Oracle MAF perspective, you should now see little orange decorations on your projects showing that they are checked into your repo.

Building and Deploying Your App From the Command Line

To run the application from the command line, we're going to clone a new local copy of the repo on the command-line and then run the build. This means opening a Command Prompt (cmd.exe) on Windows or a Terminal (bash shell) window on Mac and Linux.

First, go to some directory that is different than where you created the Git repo above. Say "C:\temp\my-test-repo" (Windows) or "/tmp/my-test-repo" (Mac/Linux). Now clone the repository you created in the previous section. Go back to the Git perspective, right-click on the repository in the "Git Repositories" perspective and select "Copy Path To Clipboard". Now type this command in your command prompt, replacing "/Users/cbateman/blog-git/.git" with you the contents of your clipboard:

  git clone /Users/cbateman/blog-git/.git

When this command completes, change into the sub-folder that got created. The folder should have the same name as the second to last segment of the path you pasted from the clipboard. In the case of the above command, the folder will be called "blog-git". Once in the directory, list the contents using "dir" on Windows or "ls" on Mac/Linux.

cd blog-git
ls

You should see the three folders for you application (HelloWorld, HelloWorldApplication and HelloWorldView). Now change into the bin folder for your target.

  cd HelloWorld/.main.android/bin

You are now ready to execute a build from the command-line. We do this by running ant with the "build" target. You need to specify two "-D" parameters to make sure it builds what you want. The first, parameter is "oepe.user.config.override.profile=releng". This tells the build to use the releng profile folder that you created above. The second parameter is "env.WORKSPACE". We configured this above so it would pick up from the environment. We did this for convenience since that is how we will get it on Hudson in the section below. For this step though, we'll just override it from the command-line to make life simpler (you could also set it in the shell environment if you prefer).

The command to build will look like this. You will need to adjust the env.WORKSPACE value to be the absolute path the folder that contains your three projects.

ant build -Doepe.user.config.override.profile=releng -Denv.WORKSPACE=/tmp/my-test-repo/blog-git

Once the build has completed, you can look at the output in ../build/debug. This contains all of the staged artifacts ready for packaging and deploying. At this point, you can call one of two targets, "dist" and "deploy". This first target, "dist" will take the build results and assemble them into an APK file that is signed with the default development certificate (release signing is covered below):

ant dist -Doepe.user.config.override.profile=releng -Denv.WORKSPACE=/tmp/my-test-repo/blog-git

When this completes, you will find both an unsigned and signed copy of the apk file under /tmp/my-test-repo/blog-git/build/debug.

The second target, "deploy" will allow you to deploy the APK to your device or emulator. To do this, you will need to execute the android adb command to find your device's id. You will find adb (adb.exe on Windows) in the "platform-tools" folder of you Android SDK installation. Execute this command:

adb devices

You should see output like this:

List of devices attached
95fff5ed03fe9e6a	device

The big hex value is the device id. We need to copy and paste that into the last command parameter, maf.deploy.device.id:

ant deploy -Doepe.user.config.override.profile=releng -Denv.WORKSPACE=/tmp/my-test-repo/blog-git -Dmaf.deploy.device.id=95fff5ed03fe9e6a

Note that after calling "build" and "dist" you could alternatively just call "adb install" on the signed APK file. This will install the APK but unlike using the "deploy" target, it won't launch the application automatically. Refer to Android SDK documentation for more information on using the adb tool.

Create a release keystore for testing

We are now ready to create a Hudson job to create internal release builds. First, we need to create a self-sign certificate so we can sign our application with something more "real".

IMPORTANT: The information provided here for signing your application is for development and testing purposes only. If you are planning to release an application to customers or enterprise users, it is important that you take great care in the way you obtain and manage your signing certificates. If applicable, be sure to consult your company’s policies and procedures around using application signing certificates.

You can create a keystore with a certificate in it by using the Java keytool command:

keytool -genkey -v -keystore /tmp/my.keystore -alias myalias -keyalg RSA -keysize 2048 -validity 10000

The tool will prompt you for information to create the keystore.

Make note of the path to the keystore (I used /tmp/my.keystore), the alias name (I used 'myalias') and the passwords that you use. I used 'foobar' for both the keystore and the key alias password.

Add a Job to Hudson

Now we're ready to configure and run our Hudson job. Start your hudson instance (java -jar hudson.war) and go to the administration web page (http://localhost:8080).

From the main page, select the New Job link near the top-left. Enter "HelloWorld" for the name and leave the type defaulted to "Build a free-style software job". Click Ok.

In the configuration page we need to modify two sections: "Source Code Management" and "Build".

Under "Source Code Management", select Git and under "URL of repository" enter the same repository that you put in the "git clone" command above.

Under "Build", click on "Add Build Step" and select "Invoke Ant" from the drop down. In the "Targets" text box, enter build dist. Click "Advanced..." to expand the additional configuration options. Under "Build File", enter $WORKSPACE/HelloWorld/.main.android/bin/build.xml. Under properties, enter the values as shown below, taking care to modify the values for key.store, key.alias, key.store.password, key.alias.password to match those for your keystore.

Click Save at the bottom of the page.

Running Your Job and Finding the Results

Click the "Build Now" link for the job. After the build finishes you will find the signed and unsigned APK files under build/release in the job workspace.

The signed APK may be deployed directly to a device. The unsigned copy is useful if you want to distribute the application to a different group for resigning.

Additional Information

Oracle Enterprise Pack for Eclipse OTN Page

Oracle MAF OTN Page

Oracle MAF on YouTube 

Friday Mar 06, 2015

Using Apache Cordova Plug-ins for MAF Development Using OEPE

Using Apache Cordova Plug-ins for MAF Development
Part 1: Cordova Plug-in Sources

by Gerry Kessler

The latest Oracle Mobile Application Framework (MAF v2.1.0) has fundamentally changed the way the way that MAF developers use and deploy Cordova plug-ins with a mobile application. The OEPE version of the development environment for MAF is also significantly different from the JDevloper version. I intend for this to be the first in a series of four blogs highlighting the benefits of using OEPE for MAF development and deployment. The blog will cover the advantages of the OEPE approach for development especially when there is a team of developers.

The first topic will be on locating Apache Cordova plug-ins so that they can be used and deployed by a MAF application developed with OEPE.

Introduction

With MAF v2.1.0, the source of the plug-in is compiled and then deployed along with the application. Previous versions required complicated packaging of a pre-compiled Cordova 2.2 plug-in and was problematic. MAF v2.1.0 has made using Cordova plug-ins far easier.

OEPE has taken a flexible approach of describing a Cordova plug-in source using URLs. For this release OEPE supports the following URI schemes:
  • file:/
  • platform:/resource
Note:Currently only directory resources are supported; archive files are not currently handled.

The platform:/resource scheme should be familiar to all Eclipse developers as it is one used by Eclipse to resolve resources within an Eclipse workspace. This is the recommended scheme to use as it offers the most flexibility at this time.

Since web URLs are not currently supported to directly download during a build, the source must be made available to the file system. OEPE has made the process of finding and fetching Cordova plug-ins easy.

Step 1: Create a Cordova Project

OEPE has exposed the Cordova CLI command-line tool to allow invocation of the command to add a plug-in. The utility requires that a project in the Eclipse workspace be configured to host the downloaded plug-ins. This is done by executing the cordova create command. The user can choose to create a new project, or configure an existing one.

To create a new project use the File >>> New menu, and choose Apache Cordova Project.
Create new Cordova project

Which results in:
New Cordova project

To configure an existing project to host Cordova plug-ins, use the Configure context menu on a project.
Configure existing project for Cordova

You will then be prompted with a dialog:
Prompt to configure existing project for Cordova

As all Eclipse users know, a workspace is a virtualized file system. A project does not need to be literally contained by a workspace; a project can be "linked" from some place else. This means as long as the project is available to the workspace, it will be available to MAF. In a team environment, a developer therefore has the flexibility to host the files for a Cordova project wherever it is convenient for him and the team.

Step 2: Add Cordova plug-in from Registry...

A project that has been configured for Cordova, has a oracle.eclipse.tools.adf.mobile.cordovaNature nature. This results in a new context menu becoming available for that project.


Add Cordova plugin

The dialog uses the Cordova CLI command-line tool to download a plug-in using the cordova plugin add command. Currently there is a single Cordova plug-in registry supported at http://cordova.io.
Add Cordova plugin dialog

The dialog expects the user to supply either a plug-in id or the URL to the repository if, available. A hyperlink to the Cordova registry website has been provided in the dialog so that you can easily copy the plug-in you wish to download.
Cordova Registry

Copy and paste the Plug-in ID or Repository URL into the dialog and Execute.
Execute

The project now contains the source for the plug-in.
Execute

Conclusion

There is no requirement for a team of OEPE MAF developers to use a Cordova natured project, but there are benefits for doing so:
  • Cordova plug-in sources can be kept separated from the applications that reference them
  • A place for all "blessed" Cordova plug-in sources for one, many, or all MAF applications
  • Distinct package for source control
  • The location of Cordova plug-in sources can be standardized for a team while keeping the physical location on disk completely flexible for an individual developer by virtue of OEPE's URL referencing
  • Simplifies continuous integration. See: Continuous Integration for MAF using OEPE and Hudson

In the next blog, I will cover how to make the plug-ins available to an OEPE MAF application.

Additional Information

Oracle Enterprise Pack for Eclipse OTN Page

Oracle MAF OTN Page

Oracle MAF on YouTube 

Thursday Mar 05, 2015

Introduction to the REST Service Editor, Generation (PART 2)

Introduction to the REST Service Editor, Generation (PART 2)

By Chris Stodden

Given successful completion of the REST Service Description in part 1. We will now consume the <service description>.xmi, for generation of the java client service.


Post Conditions:

  • Generated Java Data Type Objects, represents the JSON payload

  • Generated Java Rest API Objects, represents the call behavior of the modeled API.

  • Generated Service Object, represents the rest call and response data objects. This will comprise our POJO data control and be used in the UI.

Consuming the Service Description:

With a complete “error free” service description you can press the Artifact Generation button at the top of the REST API editor page to launch the Artifact Generation wizard.




Create the connection:

Select the Base Resource Path, this will also form the basis of the connection. It is possible to have multiple base resource paths specified in your service description, this choice will filter requests to only those that derive from this path.

Note: localhost resolves to the device or emulator, so if the target Server instance is hosted on a development machine, for Windows run ipconfig, and for MAC launch Network Utility from Applications to determine the IP address.



Overriding Java Class and Package Naming Behavior

By default the names in the generated artifacts are based off of the names derived from the REST service API paths. Where this is not desired, the names can be overridden to something more preferable.




Generation Settings:

Designate the source directory where artifacts are to be generated. In addition, the package prefix can be specified.

Note: It is recommended to choose a different package prefix for each Base URL that may be used to generate artifacts. This will keep the dependencies clean and minimize any overlap in resources that may have the same name.

By choosing to generate the service class, this will form the basis of the POJO data control. Also, choose to update the project classpath with MAF REST runtime libraries required to deploy and run our REST client.



Request Selection

The user must select the requests to be invoked from our rest service class. The requests chosen here will form the content of the generated service class. This will enable REST client interaction with the targeted service.

Note: By not checking Generate Service Class, this page will be bypassed and will simply generate the REST API and Data Type classes.




Generation

Data Type Objects:

The generated data type object getter and setter names will follow basic java bean conventions. When java bean naming cannot be preserved to maintain a relationship to the JSON payload, the annotation, “@DataType(name="location-id")”, with the name attribute is added for proper serialization/deserialization mapping. In addition, the data type annotation will convey type information for generics, as well as, multiple=true or false for collections (for example, “@DataType(type=EmployeeObject.class, multiple=true)”). Looking at the DepartmentsObject and DepartmentObject, the data type structure represents a JSON object wrapping a JSON array.


Rest API Objects

The generated REST API objects follow logical package and naming patterns consistent with the model represented in the REST API Editor. The Base Root object can be found in the <package prefix>.restapi package. Navigating via Project Explorer to sub-packages you find child path segment objects that contain the corresponding requests.




Client Service Object:

The client service class is generated with the class name and rest requests we designated. This class may or may not be in a desired form to create a POJO data control.



Given that DepartmentsObject contains a collection, we can change the method return type to return the Collection of DepartmentObjects. This is what we plan to consume in the AMX page.



Create DataControl:

Right-click, select Model Components, Create Data Control...



Adding the DataControl to the Page

Open the RESTService DataControl in the Data Controls palette and drag the departmentList onto the page.



Select List View, and choose to have the name as the text element.



Deployment

At this point, the application should have a minimal set of artifacts for performing a simple REST client transaction and display the contents in the AMX page just created. Create a MAF Application Run Configuration, Select your Assembly Project and Run It.

Note: deployment requires a JDK. Navigate to Windows>Preferences>Java>Installed JREs and Add Java8 JDK. Then, navigate to Windows>Oracle>Mobile Application Framework>Launch and select the JDK.





">

Future Topic:

Take a closer look at the generated code, characterize the structure, annotations, and behavior of the data type, rest api, and service.

Additional Information

Oracle Enterprise Pack for Eclipse OTN Page

Oracle MAF OTN Page

Oracle MAF on YouTube 

Wednesday Mar 04, 2015

Introduction to REST Service Editor (PART 1)

Introduction to the REST Service Editor, Part 1

By Preston Appel

With the MAF 2.1 release, OEPE users can now easily develop applications that interact with REST APIs. All the tooling that has been added is available via the REST Service Editor. This editor allows the user to experiment with existing REST APIs and to describe their requests and related data types. This blog covers the basic functionality of the editor and its REST Client, REST API and Data Types pages, by showing how you can send a simple GET request to a server and then store a description of the request and of the received payload. Part 2 of this blog leverages this description to generate Java 8 code that consists of an API that can be used to send the request and to consume the received information programatically.

Preliminaries

This blog assumes some knowledge of MAF development with OEPE. To create a REST service description that we’ll modify in our REST Service Editor, we need a MAF 2.1 application. Here is an outline of how to create it:

  1. From OEPE, click on File/New/MAF Application
  2. Enter the Application display name, confirm that the Runtime version is 2.1.0 and click Next
  3. Alter the project names and default packages as desired and click Next
  4. Add a deployment target, if necessary, and click Finish
  5. Click Yes to open the Oracle MAF Perspective, if prompted

Please refer to the documentation if you need further details.

Creating a REST Service Description

We can begin exploring REST services by creating a REST Service Description, an XMI file that will be modified by our REST Service Editor. REST Service Descriptions can only be created in the view project of a MAF 2.1 application. Below, we create this file by clicking the context menu’s File/New/REST Service Description.
Create a new REST Service Description

On the REST Service Description dialog, enter a new file name, if desired, and click Finish to complete creation of the XMI file and open the REST Service Editor.
REST Service Description wizard

From the image below, you can see the first page of the REST Service Editor: REST Client. The REST Client page is for experimenting with existing applications that expose REST APIs. This page is not part of the persistent state of the REST Service Description, so changes neither dirty the editor nor are they persisted when you save the editor.
REST Service Editor's REST Client page

Testing REST APIs with the REST Client Page

Now, let’s invoke a REST API. For the purposes of this blog, we have a simple resource that will return a list of departments. We start by entering its URI in the Address field. Note that we’re using a GET method.
Address field on the REST Client page

Currently, the editor is geared toward JSON REST services, so we will need to get a JSON payload if we want to import it to create data types. To do this, we modify the Request Details by adding a header to indicate that the request will accept application/json payloads. We do this by clicking the add icon on the Headers tab of the Request Details section. The Add Header dialog supports content assist.
Add Header dialog from the REST Client page

The Headers can be edited, deleted or reordered.
Request Detail's Header section on the REST Client page

After entering the method, address and header, we are ready to send our request. Click on the Send Request button to get a response.
Send Request button on the REST Client page

The status in the Response section indicates that we have successfully sent our request and received a response back.
Response section on the REST Client page

For the purposes of this blog, the more interesting view of the response is the Rendered Content. This will give us a good idea of what data types will be created when we import this JSON payload.
Response section's Rendered Content tab on the REST Client page

We have received back a JSON object containing a JSON array called "departments." Within each department, we have an object (a department) with an id and an array called "employees." The employee object has departmentId, id and name attributes. While not shown, the last employee object also contains a manager object, which is just another employee (at least in our payload). There’s more information on how this payload is imported in the data types section near the end of this blog.

Importing the Request and Data Types

Now we’re ready to import the request and data types from what we have entered on the REST Client page of the editor. Importing this information will allow us to replay the same request in the future and also to generate useful artifacts (like Java code) from it.

To import the request and data types, click Import the REST Client Information at the top of the editor.
Import the REST Client Information button on the REST Client page

We can choose whether to import the request, the data types or both from the information on the REST Client page. Since we want to describe both a REST API and the data types, we leave both checked and click the Next button.
Import REST Client Information wizard's Selection page

We now have some choices about importing the request. First, we set up the root path. It is generally a good practice to split the address up such that a new path is created for each of its segments. This tree structure allows for requests on each of the path segments. In the Root Path field, we’ll break "http://localhost:4545/departments" right after 4545 (by deleting "/departments") so that the "http://localhost:4545" becomes the root path. The "departments" segment will then be created as a child of the root path. In the Importing Revisited section, we’ll import "http://localhost:4545/employees" so that you can further see how this works. We also supply a name for the request, "getDepartments," and click Next.
Import REST Client Information wizard's Import Request page

Finally, we have some information about the data types that will be created. Note in the image below that the box is checked to set the request output to a representation with the appropriate data type. This means that our REST API will then know what data type to use for the data that is returned from the request. We now click Finish to execute the import.
Import REST Client Information wizard's Import Data Type page

Describing the Request on the REST API Page

The import process takes us to the REST API page because we chose to import the Request. Looking at the Outline, we can see that our GET request, "getDepartments," was created and that it has the HTTP Header that we added to it: "Accept=application/json." Also note how a tree of paths was created from the root path and the "departments" segment.

Regarding the editor itself, the asterisk next to the file name at the top of the editor indicates that the file is dirty. This operation has modified the XMI file. It is easy to back out changes, such as this import, since the editor fully supports undo and redo.
REST Service Editor's REST API page

Looking at the Output tab of the Request, we see that, as requested in the import wizard, we now have the representation output appropriately set to Departments1 (the top level object from our JSON payload). We’ll look at the data types in a moment, where we can change the name of Departments1 to something more appropriate.
Request section's Output tab on the REST API page

Probably the safest and fastest way to describe an existing REST API exposed by an application is to use the import process that was just described above. However, new paths and requests can be manually added to the REST API page or existing ones altered. If you do that, it is recommended that you use the Copy to REST Client button, available on requests, so that you can test the work you have done.
Copy to REST Client buttonon the REST API page

Describing the JSON Payload on the Data Types Page

Click on the Data Types tab to see how the JSON payload was imported.
REST Service Editor's Data Types page

Looking at the Departments data type, we see how the JSON payload below maps to what was created.
Departments JSON payload

Departments is a complex type because it has attributes. The id and name are simple attributes, a json.Number and json.String respectively. The employees array has become a complex attribute of data type Employees (it’s plural because the name generator for the data types uses the array name "employees"). The manager type is also the complex type Employees.

Now, the data type Departments is plural for the same reason that the data type Employees is plural— its name is generated from a name in the JSON payload which is plural. But the data type really does just represent a single department. We can easily fix this by simply changing the name to Department. I’ve also changed the name of the Employees data type to Employee since it also represents a single employee.
Departments data types on the Data Types page

So where does the name Departments1 come from for the top-level JSON object in the payload? This comes from the last segment of the address, which is "departments." The name generator had already used the name "Departments," so "Departments1" is used here. Now that we’ve changed the data type Departments to Department, let’s change Departments1 and save the description file. Also note that the Data Types page tells you which requests use a particular data type.
Renamed data types on the Data Types page

As we’ve seen, we can manually alter data types by changing their names. We can also add attributes and new data types. But how does changing an imported data type affect subsequent imports of JSON payloads that use that same data type?

Importing Revisited

Let’s change the address to "http://localhost:4545/employees" on the REST Client page and send the request. We’re still using the GET method and still have the "Accept=application/json" header. We get back a list of employees as our JSON payload.
Employees JSON payload

On importing the employee data, we will import both the request and the data types.
Import REST Client Information for employees JSON payload

The import functionality recognizes that we already have the "http://localhost:4545" root path, so it tells us it will just be creating the child "employees" path. We also provide a name for the request, "getEmployees."
Import Request wizard page for employees JSON payload

Finally, the import wizard tells us what data types it will be importing. Even though we previously renamed the data type Employees to Employee (singular), the wizard sees that the Employees JSON object is the same as (or similar to) the existing Employee data type and offers to use Employee rather than creating a new Employees type, if the “Merge types into the existing matching domain types” box is checked. (Employees1 in this case would come from the last segment of the address "http://localhost:4545/employees" and is the top-most JSON object in the JSON payload.)
Import Data Type wizard page for employees JSON payload

Here we see how we’ve continued to expand the tree of paths with the "employees" path. And remember that each path can have its own requests.
REST API page showing getEmployees request

Moving to the Data Types page, we see how the Employee (singular) data type from our previous import was used and a new Employees1 data type has been created.
Data Types page showing employees import

And to finish the work of describing data types for this blog, I’ve changed the name of Employees1 to Employees and saved the editor.
Data Types page showing final version of employees import

Next Steps: Code Generation

We’ve now experimented with invoking an existing REST API through the REST Client page. That information has been imported to describe the REST API and its associated data types. In the future, we can use the REST Service Description we’ve created to replay the requests through the Copy to REST Client functionality. The description also serves to document the REST API.

Once we’re satisfied with our description of the REST API and the data types it uses, we can also generate Java code from it. That’s covered in Part 2 of this blog.  

Additional Information

Oracle Enterprise Pack for Eclipse OTN Page

Oracle MAF OTN Page

Oracle MAF on YouTube 

New Mobile and REST tools come to OEPE 12.1.3.4

Oracle Enterprise Pack for Eclipse (OEPE) 12.1.3.4 is a major feature release which provides new design time and runtime tools for Oracle Mobile Application Framework (MAF) 2.1.0 and new tools for REST service development.

Support for Oracle Mobile Application Framework 2.1


OEPE 12.1.3.4 includes new design-time support for and ships the Oracle Mobile Application Framework 2.1. Oracle MAF 2.1 new features include:
  • Support for Java 8 - Java is the language used for business logic development on Oracle MAF, in fact Oracle MAF is the only solution out there that will run the same Java code on both iOS and Android.  Now developers can leverage the latest features of the Java language - such as Lambda expressions, Collections with Generics and more - while running on a 64bit JVM that supports the Java 8 Compact2 profile.
  • Cordova 3 support - Cordova is used in Oracle MAF to provide access to device features. Oracle MAF 2.1 updates the Cordova version to 3.6.3 on Android and 3.7 for iOS, dramatically increasing the number of available plugins that developers can leverage.
  • Simpler Cordova Plugin integration - Oracle MAF leverages the plugman command line to build and incorporate plugins into Oracle MAF apps.
  • Xcode 6 and Android 5 support - use the latest SDKs to compile and deploy your MAF applications across multiple devices.
Additional details for the MAF 2.1 runtime features can be found here and release notes can be found here.

New REST Service Development Tools


Oracle Enterprise Pack for Eclipse 12.1.3.4 provides a new robust editor for developers who work with REST services. The new REST Service Editor includes the following capabilities:
  • Wizards to create a REST service description
  • Invoke REST operations and analyze the Response payload with multiple representations for returned data types 
  • Create complex JSON Request payloads to test deployed REST services
  • Support for multiple security protocols including OAUTH and Basic Auth
  • Generate Java clients of the REST Service based on the service description
  • Create Data Controls to easily bind MAF components to the REST service operations

REST Service Editor in Action

Additional Information

Oracle Enterprise Pack for Eclipse on OTN

Introduction to the REST Service Editor

Code Generation with REST Service Editor

OEPE YouTube Playlist for Mobile Developers

Oracle MAF Blog


Tuesday Sep 30, 2014

OEPE 12.1.3.2 brings new support for Oracle Cloud and Mobile

Oracle Enterprise Pack for Eclipse (OEPE) 12.1.3.2 was released this week and is a major feature release which provides new support for Oracle Developer Cloud Service, Oracle Mobile Application Framework 2.0.1, Glassfish Server 4.1, and new certification against Eclipse 4.3.1 (Luna SR1)

Support for Eclipse 4.4 (Luna) SR1


Oracle Enterprise Pack for Eclipse (OEPE) 12.1.3.2 now fully supports the new Eclipse 4.4.1 (Luna). All in one zip distributions and plugin repositories are now based on Eclipse Luna SR1.

Oracle Developer Cloud Service Tools

OEPE 12.1.3.2 includes new support for the Oracle Developer Cloud Service, a new cloud-based team development environment.

ODCS Tooling Support Includes
  • Updated Oracle Cloud view which lists Developer Cloud Service accounts and projects
  • Connectors to interact with the hosted GIT repository
  • Mylyn Plugins to connect to and interact with the Tasks issue tracking system
  • New editors to update and create Tasks within Eclipse and define custom queries
  • Mylyn Connectors to interact with Hudson Continuous Integration Server
  • Cloud Synch Tools to help you push your projects up to the Cloud for the first time. The Synch wizard will assist with setting up your GIT repository, generating Maven build scripts, updating the hosted Maven repository, and creating sample Hudson build jobs

Support for Mobile Application Framework (MAF) 2.0.1

In addition to existing support for MAF 2.0, OEPE 12.1.3.2 also now supports MAF 2.0.1. All existing MAF design time tools can be targeted to either runtime and new Migration Wizards can assist in upgrading old apps to MAF 2.0.1. OEPE 12.1.3.2 also has new support for Oracle Moblie Security Suite (OMSS). OMSS provides Mobile Application Management, Data Leak Policy Enforcement, and Containerization support

Support for Glassfish 4.1

OEPE 12.1.3.2 also includes updated support for Glassfish 4.1, enabling you to use Java 8 when developing applications with Glassfish.

Monday Sep 29, 2014

Oracle Open World 2014: Come Say Hi!

Oracle Open World 2014 is upon us and for those in attendance, its all about the sessions and wealth of knowledge readily available in a short week. At the same time, OOW provides a great opportunity to meet the teams that develop the products that you use on a day to day basis. If you are an OEPE user or interested in Eclipse, come by our booth in the Oracle Demogrounds located in Moscone South.

 The OEPE booth is located in the Database and Middleware section and Booth ID# SLM-118. We are showing demos of Mobile development, Cloud, Oracle ADF, WebLogic support, and much more.

Thursday Sep 18, 2014

Oracle Developer Cloud Service is Live!

Oracle Developer Cloud Service is a cloud-based software development Platform as a Service (PaaS) and a hosted environment for your application development infrastructure. With the Oracle Developer Cloud Service, development teams can maximize productivity with instant access to Application Lifecycle Management (ALM) tooling as well as team collaboration and management utilities in addition to seamless deployment to the Oracle cloud platform. Oracle Developer Cloud Service provides an enterprise-grade platform to develop, collaborate, and deploy applications within the Oracle Cloud with support for on-premise deployment and GitHub integration. It allows businesses to reap all the benefits of PaaS including subscription based, self-service access to reliable, scalable, and elastic cloud environments with the ability to move code seamlessly between Oracle Cloud to other clouds or on-premise. Built in integration from Oracle Enterprise Pack for Eclipse (OEPE), Oracle JDeveloper and NetBeans allow you to interact with your code in the Oracle Developer Cloud Service.

Check out the Oracle Developer Cloud Service homepage for videos, tutorials, whitepapers, documentation, and more. 

Be sure to check out the upcoming sessions and hands-on-lab at OOW '14 and JavaOne '14.

Session ID: HOL7064

Session Title: Using Oracle Cloud to Power Your Application Development Lifecycle

Venue/Room: Intercontinental - Sutter

Date/Time: 9/29/14, 11:45 - 12:45

______________________________________________________________________________ 

Session ID: CON1840

Sesstion Title: Java Development in the Cloud

Venue/Room: Hilton - Continental Ballroom 6

Date/Time: 10/1/14, 11:30 - 12:30

______________________________________________________________________________ 

Session ID: CON5031

Session Title: A Guide to Team Development in the Cloud with Oracle Developer Cloud Service

Venue/Room: Moscone South - 270

Date/Time: 10/1/14, 12:45 - 13:30

About

The focus of this blog is on Oracle Enterprise Pack for Eclipse (OEPE) and Oracle's involvement in the Eclipse community. Visit us for information on releases, tips and tricks related to Eclipse, and general Eclipse community information.

Search

Categories
Archives
« May 2015
SunMonTueWedThuFriSat
     
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
      
Today