As you hopefully know by now Bluemix.info is a news aggregator for IBM Bluemix developers and professionals covering news about everything related to IBM's platform as a service, including runtimes, services, events and much more. Curators decide which content is published on the site. To make it as easy as possible for curators, certain websites and blogs are checked on a scheduled basis whether there are new articles. If so, the information is put in a queue on Bluemix.info where curators can easily approve entries by just clicking an approve button.

This scheduled task reads new articles from websites via feeds and the open source library Rome. Check out FeedManager.java and RSSReader.java for details.

This task is triggered via the Workload Scheduler service (beta). The class SchedulerUtilities.java demonstrates how to use the scheduler service. It uses Java client libraries that you need to download and add to your project first. In SchedulerUtilities a task is created which is triggered every hour.

When the task is triggered, a REST API from Bluemix.info is invoked. In order to make sure only the task can trigger this API basic authentication is used. When the task is created a username and password is generated, passed to the scheduler service and stored in Cloudant. Before the REST API runs the core functionality it checks this username and password.

Since yesterday the workload scheduler service provides a nice dashboard that allows you to monitor your tasks.

Usage of the Data Cache Service in Bluemix.info

By Niklas Heidloff, posted on Dec 17, 2014

In order to scale Bluemix.info we run multiple instances of the application. In this model applications cannot cache data only in an instance/Java runtime since you cannot assume that the data in the runtimes is always in synch. For example when adding a news entry via one application instance the in memory cache of the second instance would be stale.

One solution to address this is to store all data in a database and always query that database for the latest data. This works but is not the most efficient option. In the case of Bluemix.info, the news aggregator for Bluemix developers, caching makes a lot of sense, since new entries are only created from time to time and in most cases only the same data is returned to different clients.

So we leverage the IBM Data Cache for Bluemix.

"IBM Data Cache for Bluemix is a caching service supports distributed caching scenarios for web and mobile applications. The caching service uses the technology of a data grid in which you can store key-value objects. Data Cache offers a business-ready, in-memory data grid (IMDG) that places the data close to the logic and keeps it there as the business scales up. It is simple to use and extends performance and scalability of existing applications."

Check out how we use this service in API.java. Essentially we always read data from the in memory cache, except the first time when the cache needs to be initialized with the data from Cloudant. Everytime a news entry or author is added, updated or deleted the cache is updated again.

In our application we use a Java library to access the data cache service. In order to compile the code locally you need to add com.ibm.ws.xs.client_1.1.jar to your build path. This file comes with WebSphere eXtreme Scale for Developers Liberty Profile that you need to download. After running the installer "java -jar wxs-wlp_8.6.0.5.jar" you can get the library file. You can find out more about this in this article.

You don't have to push com.ibm.ws.xs.client_1.1.jar to Bluemix since it's already part of the liberty buildpack. Note that even though you can compile the code locally, you can NOT access the data cache service when running the application in your local Eclipse/liberty.

To make the setup easier you might also want to consider the usage of the REST API which seems to be new (at least I haven't seen it before today).

Configuration of Bluemix Apps via User Provided Services

By Niklas Heidloff, posted on Dec 16, 2014

When Bluemix services are created and bound to applications, they usually provision all artifacts needed to use the services. As result of this provisioning they return information to Bluemix that is needed to the services, for example user credentials. This information is stored in the Bluemix environment variable VCAP_SERVICES and can be accessed from applications.

Sometimes however you need additional configuration for your applications which shouldn't be hardcoded. This can be configuration which is not associated with a particular Bluemix service or additional configuration for Bluemix services. For example the single sign on service requires a redirect URL and a client id and secret.

There are several approaches to configure Bluemix apps, for example user-defined variables which are additional environment variables. For Bluemix.info we use an user provided service. User provided services show up in the Bluemix dashboard as other services and can include configuration parameters. They can be created via the cf command line tool and then easily be accessed.



In order to access this configuration we use classes like ConfigUtilities. This class also abstracts whether the application is run on Bluemix or locally. When running locally we store the same information in local environment variables.
Bluemix provides a Single Sign On Service to authenticate users against the IBM identity provider, Facebook, Google or LinkedIn. Once authenticated applications can access the profile information of the current users, e.g. name, email, etc. Bluemix.info uses the IBM identity provider which is the one that is also used for bluemix.net and most other IBM sites using the IBM id.

The Single Sign On services comes with a sample. The sample works and is well documented but requires a bigger amount of Java code. I've reimplemented this sample as one single servlet in one file. In the servlet I use the Apache Fluent API which makes the code significantly shorter and easier to read. The servlet has to be defined in web.xml.

Before you can use the Single Sign On service you need to configure it.



Since you need to provide the redirect URL, the client id and secret and the url cannot be put in the Bluemix environment variable VCAP_SERVICES. Instead I pass this information to the servlet via a Bluemix user provided services. I'll blog more about this separately.

To identify an unique user I currently use the property "username", e.g. "http:\/\/www.ibm.com\/johnsmith@somewhere.com" and use this information to check for authorization. As I've learned later however I should use the property "userUniqueID", e.g. "{'http:\/\/www.ibm.com\/110000Z99Z'}". Turns out the userUniqueID array has only and always exactly one element.

Swagger used in Bluemix.info to document and invoke REST APIs

By Niklas Heidloff, posted on Dec 10, 2014

In my previous blog entry I described how the REST APIs of Bluemix.info have been implemented. Rather than documenting these APIs somewhere else, I've used Java annotations to do this directly in the source code. I think doing this directly in the source code is a good thing since it reminds developers that they have to update the documentation whenever they change the API (or even better don't change the API in the first place). Plus it's more efficient to do this in one place rather than having to use another tool.

There are several tools that allow doing this. For Bluemix.info I've used the open source project Swagger. Swagger contains several components, most importantly a specification for documenting RESTful APIs. I've used the older version 1.2 (but should have used version 2.0 which as I learned today is available now).

In addition to the specification there are many different client libraries and tools for different languages and platforms. For Bluemix.info I've used swagger-servlet and declared it in pom.xml as dependency. In order to configure it you need to define ApiDeclarationServlet and DefaultServletReaderConfig in web.xml and tell Swagger in which packages it should try to find the annotations.

To document your REST APIs you need to add additional Java annotations to your classes that are already marked as REST APIs via JAX-RS annotations. As an example check out the API to add authors. Via @ApiOperation the type of operation is defined, as well as the name and protocols. Via @ApiImplicitParams you can define input parameters, e.g. whether they are mandatory or optional, what type they have, default values, etc. And via @ApiResponses you define the possible responses, e.g. HTTP status codes. As input and output parameters you can also use Java classes which is really convenient since Swagger reads automatically the classes' fields/methods.

Once you've added the annotations you can access the definition of your API via URL, e.g. https://www.bluemix.info/api-docs/api.

The other great thing about Swagger is that it comes with a sample UI. This user interface displays the different APIs with their input and output parameters. Plus it allows invoking the APIs directly via some sort of API explorer. You can try it for the Bluemix.info APIs yourselves (but only api/curatednews and api/news can be invoked without authentication).

More Blog Entries ...

Hi, my name is Niklas Heidloff. I work for IBM as an IBM Bluemix Developer Advocate. The blog contains information about IBM Bluemix and articles about my previous work in IBM Collaboration Solutions, esp. IBM Connections and XPages.

@nheidloff

Disclaimer

The postings on this site are my own and don't necessarily represent my employer IBM's positions, strategies or opinions.