July 10, 2015 | Written by: Ying Zhao
Share this post:
The JAX 1.1 standard does not specify a standard REST client implementation; web developers have a myriad of means to accomplish it. Apache Wink is one of the popular methods that web developers use when developing a REST client on a WebSphere Liberty environment, such as Bluemix Liberty runtime. This blog shows how to develop such a client using a web development tool (Eclipse) and deploy it to Bluemix.
Set up the Eclipse development environment
Before you get started, you will need to set up an Eclipse development environment on your local machine. Follow the online instructions below:
Implement REST service
Now that we have a working development environment, the next step is developing a REST service to be called by the REST client. In our sample, the REST service is implemented by following the instructions in REST Web Services in WebSphere Liberty, an excerpt from the book Modern Web Development with IBM WebSphere by Kyle Brown et al and published by IBM Press. Once you’ve completed these steps, continue to the next section.
Implement REST client
Now we are able to create and test a REST client for the REST service, which we just implemented, using Eclipse that has the Liberty profile setup as described earlier (I used Eclipse Luna version with IBM Bluemix Tools
1.0.1.v20141111_2000; you may have slightly different setup with you environment).
Create RestClientSample project
- Open “Java EE” perspective, create a new web project from menu “File” → “New” → “Web Project”, and name the project, RestClientSample
- Click on Next, ensure Liberty profile is chosen, and deselect “Add project to an EAR”
- Highlight “Java” and ensure its setup as default as shown below
- Highlight “Web Module”, and ensure its setup as shown below
- Click on “Change Features…” and ensure that “JAX-RS (REST Web Services)” is selected
- Click on “OK”, then click on “Finish” to create the project.
- In “Java EE” perspective, “Enterprise Explorer” view, expand the newly created project, RestClientSample, expand “Java Resources” underneath and find ”src”; right click on it to create a new package from the popup menu, “New” → ”package” and then “Finish”
- Click on the newly created package to create a new Servlet, RestClientServlet, as our REST client, “New” → ”Servlet”
- Click on “Next” ensure “URL mapping” is named properly
- Click on “Next”, ensure “doGet” is checked, uncheck “doPost, and then click on “Finish”.
Implement RestClientServlet.doGet method
In “Enterprise Explorer” view, double click on
RestClientServlet.java to open it in Java editor. Implement the
doGet method as shown below. The API details are in the infoCenter and Apache.
Notice the line of code
client = new RestClient(clientConfig) creates an Apache Wink REST client with predefined client configuration parameters, which are default in this case. The line
resource = client.resource("http://restservicessamples.mybluemix.net/banking/Greeting") creates a resource based on the REST service URL. The URL shows that the REST service has been deployed to Bluemix as http://restservicessamples.mybluemix.net/banking/Greeting. If the REST service has not been deployed to Bluemix and runs on a local Liberty test environment in Eclipse, this URL would have been similar to http://localhost:9080/RestServicesSamples/banking/Greeting. Finally,
resp = resource.get() makes the REST GET call to the service.
Set up server for REST client
If you would like to run your REST client on a new WebSphere Liberty server in Eclipse, follow the steps below.
- In the “Servers” view, right click, “New” → ”Server”
- Click on “Next”, click on “New” next to “Liberty Profile Server” to create a new profile server, libertyProfileServer
- Click on “Finish”. Click on “Next”, highlight RestClientSample project, click on “Add”, and then “Finish”.
- In “Servers” view, double click on “WebSphere Liberty Server” to open its configuration, click on “Open Server configuration”
- In the “Design” view, choose Feature Manager and ensure
jaxrs-1.1 is selected.
- Save all changes, before closing the server editor.
Since Apache Wink Client runtime support is a 3rd-party add-on, in WebSphere Liberty 8.5, the follow configuration is needed to turn on its support. In “Enterprise Explorer” view, “WebSphere Application Server V8.5 Liberty Profile” → ”Servers” → ”libertyProfileServer” → ”server.xml”, open
server.xml in text editor and modify the following line:
<webApplication id="RestClientSample" location="RestClientSample.war" name="RestClientSample"/>
<webApplication id="RestClientSample" location="RestClientSample.war" name="RestClientSample">
<classloader apiTypeVisibility="spec, ibm-api, third-party"/>
libertyProfileServer is the new profile server created in the prior steps to run the client. If you use a different server name, modify its
- In “Enterprise Explorer” view, Right click on RestClientSample, “Run As” → “Run on Server”, choose “WebSphere Liberty Server” as shown below, and then “Finish”. “WebSphere Liberty Server” is the server created previously.
- Check the console to confirm the server launched successfully
Deploy REST client to Bluemix
Almost done! In “Servers” view, stop “WebSphere Liberty Server”, if it is started, then follow the steps below:
- If the Eclipse tools for Bluemix plugin is installed, right click on “WebSphere Liberty Server” → “Utilities” → “package server to IBM Bluemix”
- Click on “OK”.
- Choose an unique name for the application as shown below, replacing “xxx” with an unique identifier
Note: if the name chosen is not unique, user will get “404 bad request, hostname taken” error during the process of deploying the application to Bluemix.
- Click on Next, choose “Start application on deployment”, so that the application is started, when it is deployed
- Click on “Finish” and invoke the deployed client using http://myxxxrestclientsample.mybluemix.net/RestClientSample/RestClientServlet
Note, change “xxx” to your unique identifier
If Eclipse tools for Bluemix plugin is not installed, the application should be deployed to Bluemix as “a packaged server” using
cf commands, as specified in Options for pushing Liberty Applications. Please follow the instructions for “Pushing a packaged server”.