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.


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

Oracle Enterprise Pack for Eclipse (OEPE) 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 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 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

OEPE YouTube Playlist for Mobile Developers

Oracle MAF Blog

Monday Jun 30, 2014

Android and iOS development comes to OEPE

Oracle Enterprise Pack for Eclipse adds new support for mobile application development using the new Oracle MAF framework. From within Eclipse, you can now develop hybrid mobile applications deploying to both iOS and Android devices. Some of the new features include:

Oracle Mobile Application Framework Design Time Support

  • New MAF Project Wizards help you get started with the correct project structure to start writing mobile applications
  • New MAF perspective configures your workspace with the most relevant Eclipse Views for mobile development
  • Android SDK and Apple XCode Configuration Wizards setup your Eclipse workspace to build and deploy your work to Android and iOS devices and simulators
  • AMX Tag Palette, Drag and Drop Patterns, and Smart Editors help you use and configure over 80 MAF components to develop your mobile applications
  • New Web Service Data Control simplifies binding mobile components to local and remote SOAP-based web services
  • Mobile Application descriptor editor provides a form based editor to assemble MAF applications, manage mobile security, configure Cordova plugins, and more
  • Mobile Feature descriptor editor provides a form based editor to create, manage, and reuse MAF features and more
  • Support for visual Task Flow creation, Bindings, and Data Controls in Mobile application development
  • MAF Feature and Application packaging for sharing and reuse of features across multiple mobile applications
  • AppXray dependency tracking and refactoring for MAF projects including AMX components, feature configurations, application configurations, bindings, task flows, and more
  • Deploy and Debug to Android & iOS Simulators or Devices directly from within your Eclipse workspace
  • Access Device and Simulator error logs of your running applications help debug runtime issues from within Eclipse

Oracle Mobile Application Framework Runtime

Oracle Mobile Application Framework 2.0 is shipped with OEPE zip distributions and available for download through Eclipse Update. No need to download an external runtime as the framework is included with the development tools out of the box.

Oracle Mobile Application Framework Samples

Over a dozen complete Mobile examples applications are included with the MAF tools. These sample demonstrate examples and best practices for data visualization, binding to web services, using Cordova plugins to access device features, and more. See the MAF Example Applications under the standard Eclipse Examples wizard for list of samples and detailed descriptions.

Checkout OEPE OTN page for OEPE downloads, tutorials, and documentation or see the Mobile Application Framework portal for even more information including new training videos and samples.

Monday Feb 24, 2014

Oracle Enterprise Pack for Eclipse at EclipseCon 2014

Oracle Enterprise Pack for Eclipse is representing at this year's EclipseCon 2014.  Key sessions for mobile and cloud include:

Developing On-Device Java Mobile Apps ..and Android too! 

Now you can leverage your Java development skills to build mobile applications that install and run on both iOS and Android phones and tablets. See how Oracle has brought Java to iOS and enabled you to leverage your existing skills to develop mobile applications. Build HTML5 user interfaces, integrate with native device feature (camera, GPS, etc.) and use Java for the business logic - then deploy to multiple platforms from the same code base. Learn about the Oracle Mobile Application Framework architecture and development experience in this demo focused session.

 Java Application Development Lifecycle in the Cloud

Looking for a simpler way to do collaborative team development, automate build and deployment and track your code life cycle? Now you can get all of these services in the cloud, and work with them directly from Eclipse. In this demo-driven session, we will explore how to quickly provision a development environments, manage application source code with GIT and Maven, track development Tasks using Mylyn-based issue tracking system, collaborate with teammates on code changes with Code Review, document development processes with hosted Wikis, and implement Continuous Integration and Continuous Delivery with Eclipse Hudson. All without the need to install and maintain the server infrastructure.


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.


« March 2015