A Stardog App in Pivotal

Let’s build a Stardog app in Pivotal Cloud Foundry.

We already talked about how to run a Stardog Service Broker inside of Pivotal Cloud Foundry. Now we will see how to create a Stardog app that uses Stardog Pivotal Cloud Foundry infrastructure.

A Simple Sample

I built a very simplistic sample application so that you can follow along with this blog post. You might want to read A Stardog App in 5 Easy Steps, too.

Our Pivotal app is a REST service that records data about what clients have connected to the server and when. It serves the data in JSON. It has four endpoints:

1. /add: a POST causes the caller’s IP and the time of day to be written to Stardog.
2. /select: a GET returns every entry in JSON by querying Stardog.
3. /clear: a POST deletes the relevant Stardog graph.
4. /vcap: a GET returns the value of the VCAP_SERVICES environment variable. Note: this is highly insecure and is only here to show you how everything is working internally.

Service Instance

To run the application Stardog for Pivotal Cloud Foundry Service Broker has to be running. My most recent blog explains how to make that happen. To verify that it’s running, log into the PCF App Manager and look for the service instance named stardogservice1. It should look something like this:

Build & Launch

First, let’s grab the source from Github and build it with gradle:

$ git clone https://github.com/stardog-union/cf-example
...
$ ./gradlew build
:compileJava
Note:
/Users/bresnaha/Dev/CF/cf-example/src/main/java/com/stardog/example/cf/web/CloudFoundryConnectionFactory.java
uses unchecked or unsafe operations.

...

BUILD SUCCESSFUL

Total time: 8.64 secs

Second, now we can launch it. Detailed instructions on how to launch applications into Pivotal Cloud Foundry are available elsewhere. We will discuss some of the basics here.

Notice the manifest.yml file in the home directory of the checkout. This file describes everything needed to deploy into Cloud Foundry.

---
applications:
- name: stardog-cf-example
  memory: 512M
  random-route: true
  path: build/libs/stardog-cf-example.jar
  services:
  - stardogservice1

Pretty simple stuff. path is the relative path to the jar file into which app was compiled. name just needs to be a unique name that describes your application. services is a list of Pivotal Cloud Foundry service instances to which your application will be bound on startup. Earlier we created a service instance named stardogservice1 and thus that is the name in our services list.

When an application is bound to a service, Pivotal Cloud Foundry first contacts the Stardog service instance and requests a binding. The service instance then reaches out to Stardog and requests that a new user be created that will have read/write access on the associated database. The service instance then returns all user authentication and location information to Pivotal Cloud Foundry.

At this point Pivotal Cloud Foundry is ready to deploy the application, which includes setting VCAP_SERVICES for use by the app.

To launch the application make sure that you are logged into your Cloud Foundry environment and that cf is in your path. Then run this:

$ cf login --skip-ssl-validation -a https://api.sys.pie-21.cfplatformeng.com
API endpoint: https://api.sys.pie-21.cfplatformeng.com

Email> admin

Password>
Authenticating...
OK

Select an org (or press enter to skip):
1. AppDynamics-DB-Visibility
....
14. stardog-broker-org

Org> 14
Targeted org stardog-broker-org

Targeted space stardog-broker-space



API endpoint:   https://api.sys.pie-21.cfplatformeng.com (API version: 2.65.0)
User:           admin
Org:            stardog-broker-org
Space:          stardog-broker-space

Now push the application with its associated configuration in the metadata.yml file into Cloud Foundry:

$ cf push

Using manifest file /Users/bresnaha/Dev/CF/cf-example/manifest.yml

Creating app stardog-cf-example in org stardog-broker-org / space stardog-broker-space as admin...
OK

Creating route stardog-cf-example-monoplegic-improvableness.cfapps.pie-21.cfplatformeng.com...
OK

Binding stardog-cf-example-monoplegic-improvableness.cfapps.pie-21.cfplatformeng.com to stardog-cf-example...
OK

Uploading stardog-cf-example...
Uploading app files from: /var/folders/v6/5bp2tjsn00n0_sm9bz87s_h40000gn/T/unzipped-app128703839
Uploading 1.8M, 177 files
Done uploading
OK
Binding service stardogservice2 to app stardog-cf-example in org stardog-broker-org / space stardog-broker-space as admin...
OK

Starting app stardog-cf-example in org stardog-broker-org / space stardog-broker-space as admin...
Downloading binary_buildpack...
Downloaded go_buildpack

.....

     state     since                    cpu    memory      disk      details
#0   running   2017-05-24 01:03:52 PM   0.0%   0 of 512M   0 of 1G

After that’s finished successfully, point your browser back to the application manager to see if the app is live:

Click on Route to see the base URL of the application:

Note the value https://stardog-cf-example-monoplegic-improvableness.cfapps.pie-21.cfplatformeng.com. In this example it will be the base URL for the applications REST endpoints.

Using the app

Now that the application is running inside of PCF we can play with it using curl. Start by getting a listing of all the connections that have registered with the application so far:

$ curl -s -k https://stardog-cf-example-monoplegic-improvableness.cfapps.pie-21.cfplatformeng.com/select
{
    "connections": [],
    "message": "Got the listing",
    "status": "SUCCESS"
}

As is expected when we first start the application there aren’t any connections yet. Let’s POST to the /add endpoint to register one:

$ curl -X POST -H 'Content-Length: 0' -s -k https://stardog-cf-example-monoplegic-improvableness.cfapps.pie-21.cfplatformeng.com/add
{
    "ip": "130.211.2.44",
    "message": "Successfully added a new connection",
    "status": "SUCCESS",
    "time": "1495672090911"
}

Now that we have registered a connection with the application we can look at the updated list by again:

$ curl -s -k https://stardog-cf-example-monoplegic-improvableness.cfapps.pie-21.cfplatformeng.com/select
{
    "connections": [
        {
            "IP": "130.211.2.44",
            "time": "1495672090911"
        }
    ],
    "message": "Got the listing",
    "status": "SUCCESS"
}

Inside the application

Let’s look inside the app to get a better idea about what’s going on.

Connecting to Stardog

The first thing to look at in the sample application is how a connection to the Stardog database is formed. The class CloudFoundryConnectionFactory is designed to make this easy. Its job is to parse the VCAP_SERVICES environment variable to find a matching Stardog service, as well as its associated connection and authentication information.

Our sample app uses the default constructor, which uses the first Stardog service in the list. In most cases there will only be one and thus the default constructor will be the right choice. However, if the application is bound to multiple Stardog service instances, then specific ones can be selected based on their instance and plan names by using some of the alternative constructors.

Once CloudFoundryConnectionFactory is instantiated, its connect() method can be called to create a Connection object, which can then be used to interact with the Stardog database.

Endpoint Handlers

The sample application uses Spring Boot. In the StardogController class there are four methods annotated with @RequestMapping which represent the entry points of our four endpoints. The value and method parameters describe which method maps to what endpoint.

For example, the /select endpoint is mapped to the getAll() method.

In it we see the following lines of code:

Connection aConn = mFactory.connect();
String aSelectCommand = "select ?s ?ip ?time where { ?s <" + aIpPredicate + "> ?ip ." +
                        "?s <" + aTimePredicate + "> ?time }";
TupleQueryResult aRes = aConn.select(aSelectCommand).execute();

This forms a connection to the Stardog database from the mFactory object which is a class member of the CloudFoundryConnectionFactory object. The getAll() method then uses that connection object to form queries in the standard ways described in the Stardog API docs.

Summary

Stardog is now a first class citizen in Cloud Foundry applications. Creating connections to a Stardog app is done with the same patterns common to most Cloud Foundry applications. While this series of blog posts explains the design and process in some detail, a real development process will be quite familiar to Cloud Foundry developers.

Download Stardog today to start your free 30-day evaluation.

• Cloud
• App Development