SOA design is in many ways an extension of object-oriented (OO) design, so we can apply much of what we already know to SOA design.  Let’s start with the concepts of coupling and cohesion.

Coupling

It is commonly accepted in the software engineering community that loosely-coupled classes make for better OO designs, because, in general, loose coupling can minimize the scope of changes that must be made to components within the system over time and can enable component reuse. Over the past several years, new schools of thought have emerged that expand on this concept to separate some aspects of a software application’s control flow from the application’s business logic. This Inversion of Control concept (aka Dependency Injection) has been embodied in the Java language (though annotations) and is supported by some application component frameworks (e.g. Spring and EJB containers). The same loose-coupling concept should be applied to services, and one key way to limit coupling is to separate business process workflows from business logic. Services should provide business logic, but we don’t want to bake workflows into the service logic because to do so would reduce the flexibility of the architecture. We want the option of changing the way business process workflows unfold, we want to promote reuse of business logic across multiple business processes and we want to enable our system to expand to meet new business demands, all without the need to significantly change the services.  Extracting the workflow logic into a separate “orchestration” layer enables us to do just that.

Figure 1. An example of a business process implementation where the workflow orchestration is embedded within the service logic.

Figure 1 illustrates the idea of embedding workflow orchestration into services.  Service A is the entry point for the start of a business process — assume it is invoked by a client application — and Service A then calls Services B and C in order, blocking for each response.  Service C then represents a subordinate business process, which calls and blocks for other services (D & E).  The point to make from this simple diagram is that the business logic becomes intertwined with workflow if we don’t take steps to explicitly separate it.  Service A has explicit knowledge of Services B and C, and its business logic is wrapped around invocations of those services, which locks that business logic into a specific business process.  We can do better by extracting the business process orchestration into a layer above the business logic.

Figure 2. An example of a business process implementation where the workflow is orchestrated by separate, specialized services.

Figure 2 illustrates an alternative approach, where we utilize separate orchestration services to create the workflow across the services, which are design to behave independently.  I’ve omitted any notion of ordering from the diagram to avoid comparison with the original workflow in Figure 1.  When workflow is omitted from the services, we must design them to operate independently around a cohesive set of business functions, which could change the invocation strategy altogether to avoid the need to manage state across transaction boundaries.  So, although there would certainly be an invocation order for the architecture illustrated in Figure 2, it would not necessarily look like the original workflow in Figure 1, and the important point is that the services should have no idea of the order in which they are invoked or of the other services in the business process.

Scripting grammars such as BPEL and BPMN, and supporting orchestration engines (e.g. ODE, Maestro), are commonly used to develop orchestration services such as those illustrated in Figure 2.

Cohesion

Just like we desire high cohesion in OO designs, we also want it in the design of services.  Each service should encapsulate a collection of strongly-related functionality, which will promote modularity, enable reuse and reduce coupling with other services.  Before we talk about how to group functions into services, it is useful to talk a bit about the different types of services that we can expect to develop in an enterprise system.  My favorite conceptual reference on this subject is the book Applied SOA [Rosen, et al.].  The authors describe a variety of different services, but the most significant are illustrated in Figure 3 below.

Figure 3. Different classes of services have different levels of interface granularity.

The most significant services — and probably the most challenging to interpret — are the Business and Domain services.  The authors of Applied SOA define these service types in terms of granularity and accessibility.  Business services are the coarsest (encompassing the most scope) and have the broadest accessibility (enterprise wide), followed by Domain services, which are medium-grained and are limited in accessibility to support Business services inside the enterprise.

To understand the role of a Business service, it is illustrative to examine the public service interfaces of prominent systems, such as the Twitter REST API.  Twitter’s REST API constitutes the system’s publicly-exposed (enterprise) service interfaces, categorized into their major business functional areas (e.g. Tweets, Timelines, Users, Local Trends, Friends & Followers, etc), so these interfaces can be considered examples of Business services, which invoke Domain and Utility services that are not publicly exposed.  For example, the basic service for updating a user’s status (aka posting a tweet) involves functions such as user validation, geolocation, URI shortening, linking references to other users and hashtags, conversation threading, etc.  Some of these functions are satisfied by Domain and Utility services that are not publicly accessible.

The scope of Twitter’s Business services do not limit the range of potential business processes.  The independent and functional nature of Twitter’s public interfaces enables external applications to retrieve and correlate data using multiple interfaces in many different ways, which may not be possible if the services were conflated with business process logic.  The multitude of third-party Twitter clients and data analysis tools is a testament to the value of decoupling business logic from business processes.

Utility services and Integration services are more straightforward to understand.  Utility services in our Twitter example might be used to perform simple, reusable functions, like sorting a list of tweets or returning a human-readable city name from a lat/long.  Integration services are used to integrate legacy applications and generally provide a mediation facility between the interface technologies used in the new system and the interfaces of the legacy application.

Business Process Definition

So, how do we go about decomposing our system into a loosely-coupled, cohesive set of Business and Doman services?  It is important to understand that we really have two goals.  The first is to develop an understanding of our system’s business processes so that we can understand the behaviors and workflows the software must support.  Understanding the business processes is what will allow architects to identify cohesive sets of behaviors that should be aggregated into individual services.  However, our second goal is to avoid “over fitting” our architecture to our known set of business processes.  We want to continuously think about the ways in which our system might need to be extended to meet evolving business objectives.  Remember what I said at the beginning of this article — we rarely ever understand the full requirements for the end product at the outset of the project, so we need to design for change.

The first step in decomposing our services is to understand our known business processes, and there are established Business Process Modeling techniques that can help, such as Use Case Analysis.  Whether you call them System Engineers, Business Analysts or Product Managers, there is likely a role within your organization with responsibility for defining business processes.  Architects are key stakeholders in the business process development activity, because identifying and modeling business processes allows architects to identify cohesive sets of behaviors and to define entry points (i.e. Business services) into those behaviors to support business process orchestration.

Domain Modeling — described in detail in Eric Evan’s excellent book, Domain-Driven Design —  is another useful analysis technique for defining service scope.  Domain Modeling can be used successfully at different levels of abstraction. At the lowest level, Domain Modeling can be used by software engineers to define an object-oriented class structure that represents the entities and relationships in the business domains, and it can be used to inform the creation of a data model (e.g. XML messages, database tables) representing those same entities and relationships.  At a more abstract level, architects can use Domain Modeling to define a system’s major conceptual entities (e.g. Customer, Account, Invoice, etc) and understand their behavioral lifecycle through the various business processes, which can help to identify cohesive sets of domain entities and their behaviors that we will encapsulate within domain services.

Related Topics

There are a few other related topics that are worth briefly mentioning.

Data Encapsulation — In my experience, it is not uncommon for software engineers to want to share data between services through a common database.  In my view, this is a bad idea and conflicts with our loose coupling goal.  Services should encapsulate their data, and access to that data should only happen through the service interface.  Software engineers will argue that this can lead to redundant data being stored in the system.  To me, redundant data should probably lead us to conclude that either the services are decomposed incorrectly, perhaps by misunderstanding the business process or domain model, or the services should not have been decomposed at all because the behaviors spread across the two services that need to share data were so cohesive that they should have been kept together.

REST vs. SOAP — Much has been written about the relative virtues of RESTful web services and SOAP-based (WSDL) web services, so I won’t repeat all of that here.  However, in my experience, SOAP-based services are more complex to develop than RESTful services.  The creation of WSDLs, designing complex XML schemas, working with a web service stack (e.g. Metro) and integrating the language-specific object-marshaling technologies (e.g. JAXB) can be challenging.  There are simply more moving parts with SOAP-based services than with RESTful services.  So, in my opinion, it is better to default to RESTful services unless there is a clear and compelling need for some of the advanced capabilities offered through the web service specifications.  However, it is worth verifying that any given WS-* specification is supported in a variety of cross-language web service stacks (many are not), or you could be trading portability for capability.

I have also come to prefer RESTful web services because I feel that they abstract away more of the software architecture details from the consumers.  SOAP-based services are often described as RPC services, because consumers reference specific methods on specific services through the WSDL.   With RESTful services, architects design interfaces around the concept of a resource and use standard HTTP methods to manage operations on those resources, which can fit together nicely with Domain Modeling to help identify and organize resources.

Conclusions

SOA is a set of architecture concepts, not a set of enabling technologies.  It is entirely possible to adopt the technologies without realizing any of the SOA benefits (beware of systems comprised primarily of legacy software that has been SOA-ized with XML wrappers).  Above all, the way we go about decomposing our system into services is motivated by a desire to instill extensibility into our software architecture and to enable reuse so that we can reduce the cost of adapting to changing business needs.  We achieve these SOA concepts by investing in developing an understanding of a system’s business processes to identify cohesive behaviors, by enforcing a separation of business process workflows from business logic and by driving our development teams to think about and design software in terms of the system’s Domain Model.

The scope of the GlassFish REST interface can be explored through the WADL file available from the GlassFish server.  There are two WADL files, one for the Management resources and another for the Monitoring resources.  The URIs for the WADL files follow below.

Management REST resources: http://serverURL:4848/management/application.wadl
Monitoring REST resources: http://serverURL:4848/monitoring/application.wadl

Using the URIs above, just point your browser to your GlassFish installation and the WADL files will be returned.  The Management WADL file is large, so it may take a while to load.  For a detailed description of the WADL schema, check out the W3C specification.

Despite what the names of the REST interfaces might lead you to believe, I’ve developed all of the features of the monitoring API library using the Management REST resources.  The Monitoring resources seem to be undeveloped, unless I am not interpreting the sparse WADL file correctly.  Either way, the Management resources provide all of the necessary capability.  Listing 1 below illustrates a small portion of the Management WADL file.

Listing 1: Partial WADL file detailing the available Management REST resources.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
    <doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Jersey: 1.5 01/14/2011 12:36 PM"/>
    <resources base="http://localhost:4848/management/">

<!-- snip snip -->

      <resource path="clusters/">

<!-- snip snip -->

          <resource path="list-clusters/">
              <method id="processGet" name="GET">
                  <response>
                      <representation mediaType="text/html;qs=2"/>
                      <representation mediaType="application/json"/>
                      <representation mediaType="application/xml"/>
                      <representation mediaType="application/x-www-form-urlencoded"/>
                  </response>
              </method>
              <method id="options" name="OPTIONS">
                  <response>
                      <representation mediaType="text/html;qs=2"/>
                      <representation mediaType="application/json"/>
                      <representation mediaType="application/xml"/>
                  </response>
              </method>
           </resource>
      </resource>

<!-- snip snip -->

  </resources>
</application>

As you can see from Listing 1, the list-clusters resource is accessed through the HTTP GET method at the URI http://localhost:4848/management/domain/clusters/list-clusters and supports four different response types.  I have used the Jersey REST client-side API for all of the REST calls in the GlassFish Monitoring API library, which conveniently abstracts away the details of forming valid HTTP calls.

Before I begin to describe the GlassFish Monitoring API software, let me be clear that this is a very early prototype, largely intended to flesh out the concepts.  I’ve started small with code to monitor clusters and their member instances, and the status data is simply written to the log — no GUI yet.  It is reasonable to conclude that there will be some restructuring of the software as I tie the API into a user interface and expand the scope to monitor more aspects of the GlassFish server.

Figure 1 below illustrates the top-level package structure for the GlassFish Monitoring API.  The client package contains a sample client that starts up the monitoring and status threads (more on that below).  As you might expect, the cluster and instance packages contain the classes for monitoring clusters and their instances.  The status package contains interfaces that are implemented by classes representing a a status monitor, a server status message and a DOM parser for XML status data.  The util package contains a few odds and ends, primarily for initializing pretty-printing XML responses from the server and to manage a configuration properties map that is built from an XML config file.

Figure 1. Top-level package structure for GlassFish Monitor Client API.

Figure 1 also depicts two interfaces — Subject and Observer.  As the names imply, these interfaces are implemented by classes that utilize the GoF Observer pattern, which is central to the organization of this API.

Figure 2 illustrates the class implementation (within the cluster package) of the ClusterListMonitor (subject) and ClusterListStatusObserver (observer).  Status monitoring and status reporting are separated into two different threads.  Monitoring classes, which implement both the StatusMonitor and Subject interfaces, run in their own thread and are responsible for polling the GlassFish server for the status of a specific item of interest (e.g. clusters).  Status observer classes implement the Observer interface, and they also run in their own thread.  Status observer classes are responsible for providing a response to the status reported by the monitor.  Responses could include updating a graphical user interface, writing to a log file or executing some predefined rule.

Figure 2. Class implementation to monitor and report cluster status data.

I had some concern about the overhead of using two threads for each unique monitored item, but ultimately thought the benefits justified the overhead.  One of those benefits is the ability to establish a wait time for the status observer thread, which decouples it from the blocking status request of the monitoring thread.  If the status monitoring thread is blocking for an unresponsive server, the status observer thread can abort the wait for a status update and take some alternative action, such as update a user interface component for a monitored item to denote the “unresponsive” status.  The ability to have this type of control over blocking status requests was one of my primary motives for developing this API.  With previous versions of GlassFish, one could only watch impatiently as the admin web console froze until the network connection to a failed server timed out.  I expect the monitoring and observer threads to manage fairly coarse-grained server items, such as the set of all clusters monitored by the classes in Figure 2, so I don’t envision more than a dozen or so unique monitored items, which would keep the number of threads acceptably low.  The instance monitor and observer classes, in the instance package, are structured similarly to the cluster classes in Figure 2.

Figure 3 depicts the interaction between the Monitor and Observer threads described above.

Figure 3. The monitor (subject) and observer run in separate threads.

The thread loop (run method) and the REST operation (queryStatusOfClusters method) for the ClusterListMonitor class are depicted in Listing 2 below.  The run method is simple — query the GlassFish server for status and notify the observers, then sleep for the user-specified time.  The REST operation is performed using the Jersey API to construct the GET operation and specify the response type, then the operation is executed on the GlassFish server and the XML response is passed back to be parsed.  See the full listing for all of the gory details.

Listing 2: Some salient portions of the ClusterListMonitor class.

//snip snip

public class ClusterListMonitor implements StatusMonitor, Subject, Runnable {

//snip snip

public void run() {
   while(true) {
      //query the GF rest interface for the cluster status
      clusterStatusList = this.queryGFStatus();
      //notify the observers of the new status
      notifyObservers(clusterStatusList);
      //sleeping for the user-specified polling rate
      try {
         Thread.sleep(pollingRate);
      } catch(InterruptedException ie) {
          logger.log(Level.INFO, "Cluster Monitor Thread Problem: {0}", new Object[]{ie});
      }
   }
}

//snip snip

/**
 * Poll the server for status and parse the XML response
 *
 * @return The status reported by the GF server
 */
public ArrayList<Status> queryGFStatus() {
    ArrayList<Status> statusList = null;

    if(restClient != null) {
        String response = queryStatusOfClusters(restClient);
        if(response != null)
          statusList = parseClusterStatusResponse(response);
    }

    return statusList;
}

/**
 * Performs the GET operation on http://baseURL/management/domain/clusters/list-clusters
 *
 * @param client The Jersey rest client
 *
 * @return The XML text
 */
private String queryStatusOfClusters(Client client) {

   //Construct the resource and perform the GET operation
   WebResource webResource = client.resource(restURL);
   ClientResponse response = webResource.accept("application/xml").get(ClientResponse.class);

   int status = response.getStatus();
   logger.log(Level.FINEST, "list-clusters Status =  {0}", new Object[]{status});

   String textEntity = response.getEntity(String.class);
   if(textEntity != null) {
      logger.log(Level.FINEST, "list-clusters Response =  {0}", new Object[]{textEntity});
      StatusUtilities.writeResponseToFile(textEntity, "cluster-status.xml");
   }
   else
      logger.log(Level.FINEST, "list-clusters Response =  No Clusters");

   return textEntity;
}

//snip snip

}

Listing 3 below illustrates a sample config.xml file, which allows the user to configure the base URL for the GlassFish REST interface, the status polling rate and the observer wait time. The config.xml file resides at the root of the JAR file.

Listing 3: XML config file allows users to specify configuration properities.

<?xml version="1.0" encoding="UTF-8"?>

<config>
  <baseURL>http://localhost:4848</baseURL>
  <pollingrate>5000</pollingrate>
  <responsewaittime>10000</responsewaittime>
</config>

Once I’ve expanded the scope of the API library, I expect to provide individual configuration properties for each monitored item.  So, for example, the polling rate could be set differently for each monitor thread.

Conclusion

As I mentioned above, this is an early prototype of the API software, and there are still several design concepts that I’m thinking through, but I wanted to get it out there so I could return to my primary project – so caveat emptor.  I’ll continue to provide updates to this library over time, but for now it will be moving to the back burner.  Feel free to contact me if you have any questions.  Have fun!

Resources

• The source code for the GlassFish Monitoring API library is available at GitHub.  The source is released under the Apache License, Version 2.0.
• The GlassFish Monitoring API library JavaDocs (still a bit rough).
• The GlassFish REST Admin API documentation.
• Here and here are a couple of blog entries that provide some introductory information about the GlassFish REST Admin API.

Each of the services follows the same, simple design approach. The RESTful resource is exposed using Sun’s Jersey API through a servlet adaptor, and the business logic is provided by a backing stateless EJB.  The EJB’s business logic for both services interacts with Twitter’s REST API (using Scribe) to exercise the oauth workflow and interacts with Amazon’s SimpleDB REST API to persist and retrieve user credential data in Amazon’s cloud.

Registration Service

The sequence diagram below illustrates the basic control flow of the Registration Service.

Figure 1. Registration Service Control Flow

Step 1: The interaction starts when a client accesses the service with a Restful web service request (GET): http://base-url/register?screenname=twitterScreenName

Step 2:  The Registration Service utilizes the Scribe OAuth library to get a request token from Twitter, using the keys that have been previously establish for the requesting Twitter client.

Steps 3 & 4: Once the request token has been retrieved from Twitter, it is associated with the Twitter screen name in a user credential object and stored in Amazon’s SimpleDB.

Steps 5 & 6:  The Twitter authorization url is created using the oauth request token, which is then returned to the invoking client (out-of-band method).

Steps 7, 8 & 9: The user must independently (hence the out-of-band) use the authorization url to retrieve the oauth verification token from Twitter, which is then provided back to the Registration Service using the following RESTful invocation (POST):  http://base-url/register/settoken?screenname=twitterScreenName&token=verificationToken

Listing 1 below illustrates the client’s entry point into the Registration Service, which is a resource class hosted in the web container with a servlet adaptor. For this service, the resource class exposes two methods via RESTful web service interfaces. The getAuthorizationURL method provides the entry point for the user to begin the registration process, and the setVerificationToken method allows the user to provide the verification token back to the service as part of the OAuth process.

Listing 1 (org.engineeringnotebook.registrationservice.resource.RegistrationResource):

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
32
33
34
35
36
37

//snip snip
@Produces("text/plain")
@Path("/register")
public class RegistrationResource {
 
//snip snip
 
    @GET
    @Produces("text/plain")
    public String getAuthorizationURL(@QueryParam("screenname") String twitterScreenName) {
       logger.log(Level.FINE, "Registration resource: getAuthorizationURL");
       String result = null;
       if(twitterScreenName != null){
          connectEJB();
          result = registrationServiceEJB.requestRegistration(twitterScreenName);
       }
       return result;
    }
 
//snip snip
 
    @POST
    @Consumes("text/plain")   
    @Path("/settoken")
    public Response setVerificationToken(@QueryParam("screenname") String twitterScreenName, @QueryParam("token") String verificationToken) {
        logger.log(Level.FINE, "Registration resource: setVerificationToken");
 
        URI uri =  uriInfo.getAbsolutePath();
 
        if(twitterScreenName != null){
            connectEJB();
            registrationServiceEJB.setVerificationToken(twitterScreenName, verificationToken);
        }  
        //need to figure out how to set the response if input parms are invalid
        return Response.created(uri).build();
    } 
}

Line 3 is an annotation enabled by Jersey and defines the base path for the service. Line 8 associates the HTTP GET operation with the specific method, and line 9 defines the content MIME type that can be consumed by the method. The @QueryParam annotation on line 10 associates a query parameter from the URL string with a specific method parameter. Line 15 invokes the backing EJB, which provides the business logic. I prefer to cleanly separate the web service interface from the business logic, and I feel that hosting the interface in the web container separate from the business logic is a good way to enforce that pattern.

JPA and SimpleDB

As part of this project, I wanted to utilize the Java Persistence API (JPA) to manage data in Amazon’s SimpleDB, since JPA is the standard Java mechanism for object-relational mapping of POJOs.  SimpleJPA is the only JPA implementation for Amazon’s SimpleDB that I could find with any significant user base, so that’s what I’ve used in my two services to persist the user credential POJOs.  There were a few challenges that I had to overcome with SimpleJPA.  The first challenge was my own ignorance about how JPA works with respect to needing corresponding getter and setter methods in the entity classes to persist and instantiate objects. I burned a few cycles trying to figure out why my objects weren’t being instantiated only to find out I was missing some corresponding setter methods. Don’t do that! :)

The biggest challenge I had with SimpleJPA was overcoming the way in which it finds entities to manage. According to the JPA2 spec, one should be able to define the persistence unit and specify the fully qualified entity class names in the persistence.xml file, which would then be picked up by the JPA implementation at run-time.  However, in all of my tests, SimpleJPA seemed to ignore everything specified in this file.  In Listing 2 below you can see where I identified the UserCredential class on line 5 in my persistence.xml file, which had no affect on SimpleJPA.

Listing 2 (persistence.xml):

1
2
3
4
5
6
7

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
<persistence-unit name="RGSPersistenceUnit" transaction-type="JTA">
<provider>com.spaceprogram.simplejpa.PersistenceProviderImpl</provider>
    <class>org.engineeringnotebook.snrdm.entity.UserCredential</class>
  </persistence-unit>
</persistence>

So, instead of relying on the persistence.xml file to define the persistence unit, I had to utilize SimpleJPA’s EntityManagerFactory’s constructor to specify the entity classes.  With this approach, SimpleJPA requires the absolute path for the entity classes, so I wrote some code to construct the absolute path, which you can find here.  For the record, I feel this is a kludge when writing code for a JEE container-managed environment.  It is generally considered bad form to reach outside of the container’s sandbox — one should instead rely on the relative paths internal to the JAR file — but after trying every permutation I could conceive of to get SimpleJPA to search relative paths, the absolute path approach was the only option that worked.  I question the portability of this method, and I’ve only tested in Glassfish 3.1, so other app servers may complain about the absolute path references.  If anyone has found a more EJB-friendly way to use SimpleJPA, please share your insights.

Listing 3 illustrates the SimpleJPA setup process. Lines 12 and 13 rely on properties that have been injected from the EJB descriptor file (ejb-jar.xml) to provide SimpleJPA with the keys to access an Amazon account. You’ll have to set those up for yourself and add the values to the descriptor file. Line 9 defines the list of entity classes that we want SimpleJPA to manage, and line 15 creates the absolute path for those classes, which is passed into the SimpleJPA’s EntityManagerFactoryImpl constructor along with the keys and the name of my persistence unit.

Listing 3 (from org.engineeringnotebook.registrationservice.ejb.RegistrationServiceBeanImpl):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

   /**
     * Sets up the simplejpa entity manager
     */
    private void initializeSimpleJPA() {
 
        List<Class> classList = new ArrayList();
        ClassPathBuilder cpBuilder = new ClassPathBuilder();
 
        classList.add(UserCredential.class);
 
        Map<String,String> props = new HashMap<String,String>();
        props.put("accessKey",amazonAccessKeyValue);
        props.put("secretKey",amazonSecretKeyValue);
 
        Set<String> libPaths = cpBuilder.getScanPaths(classList);
 
        factory = new EntityManagerFactoryImpl("RGSPersistenceUnit", props, libPaths); 
 
    }

Resource Manager Service

The Resource Manager Service is very simple, and the basic structure of the code is the same as the Registration Service. The Resource Manager Service allows an application to retrieve a protected resource once a user has authorized the application using the Registration Service. Caveat Emptor!! You would never want to expose this service to the world. Anyone invoking this service would have access to a user’s protected resources. This service is intended to be used within the security environment of the application the user has authorized.

The sequence diagram below illustrates the control flow of the Resource Manager Service.

Figure 2. Resource Manager Service Control Flow

Step 1: The interaction starts when a client accesses the service with a RESTful web service request (GET): http://base-url/retrieve?screenname=twitterScreenName&twitterurl=protectedResource

Steps 2 & 3: The service retrieves the user credential from Amazon’s SimpleDB.

Steps 4, 5 & 6: The services uses the Scribe OAuth library to sign the request and retrieve the protected resource from Twitter.

Step 7: The service returns the protected resource to the client.

Conclusion

That’s it! I’ll post more information soon about the build and deployment processes for these two services, since there are some Maven dependency issues. Now that I’ve finished the basic data access plumbing, I’m moving on to the data mining work — the fun part. My next step is to review Amazon’s Elastic MapReduce service (built on Hadoop) for its applicability to the data mining algorithm that I plan to use initially.

The Code

All of my code is available at GitHub and is released under the Apache 2.0 open source license. You can browse through the POM files to get an understanding of how to build the projects, but I’ll write more about that soon.

Registration Service

Resource Manager Service

SNRDM (common dependency)

SimpleJPA is a bit of a hassle to build because it doesn’t package up all of its dependencies, so you’ll have to manage them yourself. I believe some of them can be found in public Maven repositories, but I can’t remember which ones. Listing 4 below is cut from one of my POM files and includes all of SimpleJPA’s dependencies. When you try to build, whichever of these dependencies is not found in the public Maven repositories will have to be manually added to your local Maven repo. The SimpleJPA wiki has more information on the dependencies, but lacks the version number information. You’ll need to use the version numbers specified in my POM files.

Listing 4 (from the pom.xml file for the Registration Service EJB):

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

<!-- JPA Dependencies -->
        <dependency>
            <groupId>asm</groupId>
            <artifactId>asm</artifactId>
            <version>3.3.1</version>
        </dependency>
        <dependency>
            <groupId>aws</groupId>
            <artifactId>aws-java-sdk</artifactId>
            <version>1.1.1</version>
        </dependency>
        <dependency>
            <groupId>cglib</groupId>
            <artifactId>cglib-nodep</artifactId>
            <version>2.2</version>
        </dependency>
        <dependency>
            <groupId>commons</groupId>
            <artifactId>commons-codec</artifactId>
            <version>1.4</version>
        </dependency>
        <dependency>
            <groupId>commons</groupId>
            <artifactId>commons-collections</artifactId>
            <version>3.2.1</version>
        </dependency>
        <dependency>
            <groupId>commons</groupId>
            <artifactId>commons-lang</artifactId>
            <version>2.5</version>
        </dependency>
        <dependency>
            <groupId>commons</groupId>
            <artifactId>commons-logging</artifactId>
            <version>1.1.1</version>
        </dependency>
        <dependency>
            <groupId>commons</groupId>
            <artifactId>commons-logging-adapators</artifactId>
            <version>1.1.1</version>
        </dependency>
        <dependency>
            <groupId>commons</groupId>
            <artifactId>commons-logging-api</artifactId>
            <version>1.1.1</version>
        </dependency>
        <dependency>
            <groupId>ehcache</groupId>
            <artifactId>ehcache-core</artifactId>
            <version>2.3.1</version>
        </dependency>
        <dependency>
            <groupId>ehcache</groupId>
            <artifactId>ehcache-terracotta</artifactId>
            <version>2.3.1</version>
        </dependency>
        <dependency>
            <groupId>ejb3-persistence</groupId>
            <artifactId>ejb3-persistence</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpclient</artifactId>
            <version>3.1</version>
        </dependency>
        <dependency>
            <groupId>kitty-cache</groupId>
            <artifactId>kitty-cache</artifactId>
            <version>1.1</version>
        </dependency>
        <dependency>
            <groupId>scannotation</groupId>
            <artifactId>scannotation</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.5.11</version>
        </dependency>
        <dependency>
            <groupId>slf4j</groupId>
            <artifactId>slf4j-jdk14</artifactId>
            <version>1.5.11</version>
        </dependency>
        <dependency>
            <groupId>javassist</groupId>
            <artifactId>javassist</artifactId>
            <version>3.14.0.GA</version>
        </dependency>

Feel free to contact me if you have questions about the code.

Background Reading

A good overview of SimpleDB and SimpleJPA.

Amazon’s SimpleDB site.

Jersey API — Oracle’s site for Jersey.

Scribe — An awesome OAuth library.

Development Tools

REST Client — You’ll need a REST client to test any REST interactions other than GET operations. This one has worked well for me.

T-437 — A SimpleDB GUI Client, which you’ll want to use to verify that your data is stored as you expected.

SmartGit — A nice client GUI to help navigate Git, which is especially useful if you’re a newbie to Git like me.

To Do List

The UserCredential entity class is crudely structured to simplify my JPA testing and should be broken apart, after which key relationships between the classes will have to be defined for persistence purposes.

I’m using the old school JNDI method for retrieving a reference to my EJBs. I need to update to the Dependency Injection method.

It is likely that my software design isn’t as faithful to the REST concepts as it could be, so I’ll be taking a fresh look at ways to be more RESTful as I continue along with my project.

You are welcome to add your suggestions to the list.

The music industry lost its grip on the distribution chain when Napster and other peer-to-peer services set consumer’s expectations beyond the traditional model of buying CDs at brick and mortar stores.  Consumers were always willing to pay for the music they wanted, but they began to expect to be able to listen to that music on any device at any time, and they were no longer willing to be forced into a pricing model that was unfairly biased in favor of the music industry because of their control over the distribution mechanism.  In the end, the music industry was not able to hold back the tide of a la carte digital content delivery because consumers demonstrated that they were willing to steal the music en masse rather than acquiesce to the music industry’s demand to maintain the status quo (try as they did to maintain it).  The same outcome is inevitable for digital video distribution.  It’s here to stay and the content producers will ultimately have to get fully on board with an online distribution model.

Netflix, and Akamai, their content delivery network provider, have made some significant technical achievements to provide a quality experience for their subscribers.  They’ve built a vast network capable of staging content close to consumers  and can dynamically adjust playback quality based on available bandwidth.  Neflix has also recently jumped into cloud computing with both feet, which Computer Scientists and IT managers find interesting, but it is not really a discriminator in terms of user experience.  I don’t want to diminish any of Netflix’ technical advances, but it does not appear that it would be difficult for set-top box vendors, with their own CDNs, to replicate Netflix’ business model.  Apple has already demonstrated an ability to do just that with its music and movie delivery through the iTunes store.  So, here are a five suggested improvements where I believe Netflix has an opportunity to step up its game.

1) Add Linux Support

Netflix should support video streaming for Linux platforms (feel free to sign the petition).  The lack of Linux support has to do with the Microsoft DRM technology Netflix uses to protect their movie content from unauthorized use.  You can read all about it here.  Clearly Netflix has chosen to address the most widely-used platforms (Windows and Mac), but I believe that disregarding Linux support will prove to be a strategic mistake.  True, it is unlikely that the loss of revenue from Linux users is noticeable on Netflix’ bottom line, but it does damage their brand.  Linux users tend to be technophiles, and if they’re shut out of Neflix’ service, they’ll gravitate to an alternative that does support Linux, and where the technophiles go, the masses will follow.  The trickle of Linux users moving to an alternative service could lead to a flood of departures from Netflix, so I believe it is in their best interest to provide a Linux video streaming solution in the very near future.

2) Downloadable Movie Rentals

One of the reason’s I own an iPad is so that I can take media content with me when I travel.  Obviously airplanes are completely without Internet connectivity, and even though airports and hotels usually provide WiFi access points, the bandwidth is often so limited as to be nearly useless for accessing streaming media content, which means that Netflix is of no value to the traveler who wants to watch movies to help the time pass.  Conversely, Apple‘s iTunes store supports a downloadable rental feature that allows consumers to watch movies offline within 30 days of downloading the movie or to finish watching within 24 hours of first beginning the playback.  Netflix shouldn’t leave this discriminating feature to Apple and give an important segment of the user community a reason to build loyalty to a competitor.  Netflix should add the capability to download content to the local device for offline viewing (and they should probably start selling digital movies, just like Apple).

3) Improve Search Features

Hulu‘s search/browse experience is richer and more accessible than what Netflix provides.  With Hulu, subscribers can use a gallery view to filter movies by key words, two levels of genre, studio and production date, in addition to a few other less-interesting filters. Conversely, Netflix subscribers can only filter a gallery view by two levels of movie genre.  After some unintuitive site navigation, users can get to a sortable list (no gallery view) that supports additional filters by year, maturity and rating.  Access to the “sortable list” feature doesn’t appear until you’ve clicked through a couple of levels of pages, which means that many will not find it at all.  However, even with the sortable list, there is still no way to filter key word searches on the Netflix site.  Shouldn’t subscribers at least be able to constrain key word searches by movie genre?  I get that most people just want the simplest possible search feature, but there should at least be an advanced feature supporting multiple constraint options.  Netflix could learn a lot from IMDB‘s advanced search feature.

4) Make The Netflix Site A Portal For Movie Aficionados

I sometimes have the impression that there aren’t many true movie fanatics working at Netflix.  By making the Netflix site a portal for movie fans, Netflix can draw in potential new subscribers.  Some might argue that Netflix shouldn’t try to replicate what IMDB already does well, but I disagree.  Movie fans are a lot like music fans, who obsess over every compositional element of a song or the poetry of lyrics.  They want to explore all of the technical aspects of a musical composition and know the story behind the music and the recording artist.  Movie fans are the same, and today, IMDB is their source of information for all things movie related — for past, present and future films. Netflix should replicate the IMDB model of maintaining the current pulse of the entertainment industry (movies and TV) and provide a comprehensive database of all movies, the people associated with them (cast, crew, production team), production details, technical details and extensive biographies and linkage associations between people, movies and events (e.g. premiers, awards ceremonies, etc).  By drawing in hardcore movie fans, others will follow, which will increase the prominence of the Netflix site in both the movie industry and the fan base, ultimately resulting in more subscribers for Netflix.

5) Build A Social Network Around Netflix Subscribers

I find it remarkable that Netflix is not integrated with social networking sites like Facebook and Twitter.  It appears that Netflix started down this path with Facebook integration in early 2009, but seems to have abandoned the effort.  The link has disappeared from Netflix’ main page, although the “Facebook Connect” page is still accessible with a direct link.  However, once enabled, Facebook integration appears to be broken, as no Netflix data shows up on the Facebook wall.  Virtually every news website in the world lets readers share articles they find interesting via Facebook and Twitter.  Amazon lets shoppers share products via Facebook and Twitter.  Yet, when I rate a movie or write a review on the Netflix site, there is no way for me to easily share that information to my Facebook and Twitter accounts.  Netflix is losing a huge marketing opportunity with this omission.  It is well understood that our social networks tend to be comprised of like-minded people, so when a friend recommends a movie, it is many times more influential than the recommendation of a professional movie critic.  Aside from marketing movies, allowing Netflix subscribers to post information about the movies they’ve seen to Facebook and Twitter would help to grow the Netflix brand.  When a subscriber posts a movie rating to a social networking site, they’re not just endorsing a movie, they’re also endorsing the Netflix service.  I can only assume that Netflix is already way ahead of me on this, and a team is about to roll out their new and improved social networking integration any day now.

In addition to integrating with existing social networking sites, Netflix should build their own social network around their content, including the enhancements described in recommendation #4.  To be fair, Netflix already tried this but ultimately shuttered the site’s “Community” features to devote engineering resources elsewhere.  It also seems that Netflix’s social networking features may not have provided sufficient privacy controls to allow users to filter what they share about their viewing habits, which could have made Netflix’ social networking features unpopular.  Facebook has been slow to address the same need for granular privacy features — we don’t necessarily want to share the same things with our mom and our drinking buddies — but that doesn’t mean social networking should be abandoned.  Yes, first and foremost Netflix must flawlessly deliver content, but their competitors can do that too.  Netflix needs discriminators, and building a social network around their service could be a big one.  Today, the Netflix site is very basic.  You can search for a movie, add it to a queue and either receive it through the mail or stream it instantly.  Social networking could make the Netflix site much more engaging, which would bring in new subscribers and put them in touch with more movies they want to watch.

At a minimum, the Netflix site should allow subscribers to create a personal profile that can be shared with others.  Profiles could enable users to create and share lists of movies around genres, topics, studios, actors and directors, to subscribe to profiles for studios, actors and directors, to receive change notifications, to aggregate movie reviews and to moderate discussion forums, just to name a few potential features.  The best way to find movies we like is to find people like ourselves who like movies.  The Netflix site does support a simple subscriber profile today, which appears to serve the exclusive purpose of associating movie reviews to a subscriber, but there is no networking capability.  A crude, unaffiliated “Netflix Community” site has emerged to fill the space that Netflix is leaving unoccupied.

Apple‘s Ping social network for music is an example that Netflix could follow.  Apple understands the value of the social network — consumers buy what their friends buy — so they’ve developed Ping, which is integrated with the iTunes music store.  Netflix should also learn from what Apple has done wrong with Ping.  Households typically have one account for online storefronts, with multiple members of the household buying products through the single account.  With iTunes and Ping, this causes a confusing social networking experience.  Adults probably don’t want their children’s music purchases associated with their social network profile, and the same would be true for movie preferences.  This also tends to be a problem with recommendation systems.  If you’re sharing an account, the recommendations become polluted because each different user’s orthogonal preferences are combined into a single profile.  Netflix has an opportunity to do something new and discriminating by combining online media distribution, retail and social networking into a high quality user experience.

Conclusion

Each of these recommendations is meant to address improvements that will add discriminators to the Netflix service in an increasingly competitive market.  It goes without saying that offering current content that consumers want to watch is the single biggest discriminator for Netflix, but that is largely a business consideration to be negotiated with content producers and outside the scope of an engineer’s purview.  Netflix already offers a great service and is the clear leader in the industry, but if they are to continue to dominate, Netflix must continue to innovate in ways that enrich the subscriber experience.

1) How do I launch an instance of an Amazon Machine Image (AMI)?

You can find the answer here.  Launching an instance of an AMI gives you a running “machine” that conforms to the configuration of the specific AMI, on which you can then deploy your applications.  You can find a list of available AMIs here.

2) How do I connect to my machine instance?

You’ve started your instance, now you want to open a terminal session to it from your local workstation.  You’ll need to use SSH with the key file you generated when you launched your instance.  You can find a detailed explanation here.  The SSH command will look like this:

ssh -i keyfile.pem username@hostname

The root user login has been disable, so instead each image has a default username that you must use to SSH in to the instance.  I have found that the default user name sometimes pops up in a dialogue box when you launch the instance, but more often than not it doesn’t and you have to hunt for it.  For example, the user name for Amazon’s Linux image can be found in their user guide.  Alternatively, if you just try to SSH into your instance using “root” for the username, the connection will fail and respond with the required username.  It’s the fastest way I’ve found to find the right username, but if someone knows where I can find it in the AWS management console, please let me know.

3) How do I load my own software on the instance I started?

Amazon’s documentation isn’t very clear on this.  You’ll need to use SCP to upload files from your local machine to your running instance.  The command to upload a source file on your local machine to a target file on your running instance will look like this:

scp -i keyfile.pem source-file-name username@hostname:target-file-name

You’ll use the key file that you generated when you launched your instance (the same one you used for your SSH session).  The default username is the same one you used to establish an SSH session, described above.  The host name (public DNS) is available in the AWS management console, described in the metadata for your running instance.

4) Once I’ve gotten my AMI configured the way I want it, how do I save it for future use?

Amazon’s documentation is somewhat lacking on this subject.  It can be a little difficult to decipher the difference between an S3-backed instance and anEBS-backed instance or to understand the use cases that would motivate you to choose one over the other.  According to Amazon’s documentation:

An Amazon EC2 instance can be launched from an AMI backed by Amazon EBS or from an AMI backed by Amazon S3. Instances launched from AMIs backed by Amazon EBS use Amazon EBS volumes as their root devices. Instances launched from AMIs backed by Amazon S3 use an instance store as the root device (e.g., / or C:\).

There’s a bit of ambiguity here.  What does it mean to say that an S3-backed instance has an instance store as the root device?  After reading more documentation, what I think this means is that the state of the S3-backed images is strictly transient.  Once you terminate the instance, any changes you make to the instance configuration are lost.  For S3-backed instances, the root device persistence is on the local disk (instance store) of the machine on which the instance is running, which is only available for the life of the instance.  Conversely, when you stop an EBS-backed instance, its state is automatically persisted to an EBS volume.  Stopping an instance is not the same as terminating an instance.  A terminated instance cannot be restarted.  So, if you want to make changes to your instance configuration and keep it around for future use, you must create an EBS-backed instance, and you should only stop it, don’t terminate it.

Having said all of that, what you really want to do is to create a new AMI based on the running instanced you’ve configured.  Although there is a browser-based management console that will let you start instances of existing AMIs, it looks like one must use the command line API tools to save your configured instance..  Once you’ve created the new AMI, you can then instantiate it from the console at a future time.  The command to create the image from the instance follows below.

ec2-create-image instance_id [--name name, --description description, --no-reboot]

The instance_id can be retrieved from the web console for the running instance that you want to save as your new AMI.  The documentation for all of the command line tools can be found here.  It takes a little bit of effort to get your local environment set up to run the command line tools, but the documentation is clear and straightforward, so there’s no point in repeating it here.

I’ve only covered the basics in this post, which I’m turning into a HowTo that I’ll continue to evolve as I work through more complex use cases.  The next step for me is to push some of my existing code into the EC2 and investigate how I’ll use Amazon’s cloud features (databases, messaging, etc) so that I can nail down what my target architecture will look like.  I’m also still looking into what my development model will look like – i.e. how much code I can write and test in my local environment versus what I need to move into the cloud, since Amazon does not provide an emulation environment for developers.  More to come.

Although I have a high opinion of Glassfish and the JEE suite, I find the arguments in favor of cloud computing increasingly persuasive.  For me, a rather simple and compelling argument has to do with the accessibility of large-scale hardware.  This is a personal project, so I’m using personal resources.  In terms of hardware, that means using my MacBook and my PC server running Ubuntu.  I don’t want to go out and buy a scalable hardware configuration to use in my personal development environment, which  will inevitably be different from the deployment environment that I’d pay for at some Web hosting company’s data center.  We run into this dilemma at my day job all the time.  Our production deployment environment is an expensive N+1 configuration involving many high-end servers to support load balancing and clustering of JEE App Servers, Oracle DBs, JMS message brokers, etc.  We attempt to create representative hardware configurations in our distributed development centers and in multiple testing facilities.  This has turned out to be costly, and it has been difficult to maintain configuration control over multiple environments.  With multiple, external software vendors developing pieces of the system, the cost and complexity is exacerbated.  Just the planning and labor to install, configure and maintain so many resources in our development and test facilities is a large burden.  We’re always discovering a hardware shortfall somewhere, which takes time to resolve, which delays our software deliveries.  Our teams often end up developing and testing in non-representative environments, which leads to late discovery of complex bugs related to scalability and reliability.  As the chief architect on this project, I’m often asked to define the minimal representative hardware environment.  Good luck with that one.

Another reason I find cloud computing valuable is that it takes the hardware problem off of my plate.  I’m a software guy, so I really don’t give a fig about developing and managing an IT infrastructure.  Again, I’ll use my day job as an example.  Because we’re building our own data centers to host our software, I have to spend time attempting to give requirements to our hardware team well in advance of when we could definitively specify those requirements.  For example, how many servers will we need to host our software?  Well, I don’t know for sure until we have a critical mass of software to allow us to empirically create some meaningful performance profiles.  We may have to make several adjustments to the planned deployment configuration to address load balancing issues or resolve performance bottlenecks, yet our hardware team needs to procure hardware months in advance of our software deliveries to create testing environments and to install data centers at remote locations.  This will cause me endless pain when I have to ask the hardware team to change the production deployment configuration after installation.  Adrian Cockcroft recently made similar points when discussing Netflix‘ migration to Amazon’s cloud.

So, I’ve decided to develop my software to run within a cloud, and I’ve settled on the Amazon cloud platform.  I don’t know if it’s the best cloud architecture and toolset, but it does seem to be the most mature and widely used.  That’s good enough for me to move on.

I’ve started reviewing Amazon’s developer documentation, and after evaluating the SOAP and REST APIs, I have initially settled on using their Java SDK.  I’m now working through some of the examples and trying to get a better feel for the programming model.  It looks to me like traditional enterprise computing frameworks, like Java EE, are mutually exclusive with Amazon’s API.  By which I mean that Amazon seems to have built its own framework from scratch, supporting scalability (EC2), database access (SimpleDB, RDS), large-scale data processing (MapReduce),  messaging (SQS, SNS) and storage (S3, EBS).  There is some indication that Java EE applications can be deployed within the Amazon cloud, but this does not seem to be the model for developing new applications that are “native” to Amazon’s cloud platform.

My next step is to dive into porting my initial POJO code over to Amazon’s cloud, which means working to become familiar with their API.  I’ll provide progress updates within a few days.

On a side note, I have finally taken the plunge and started working with Maven.  I had resisted it in the past, preferring to keep my development environment simple and under my control.  However, it’s gotten to the point where it’s difficult to avoid using Maven because so many other projects use it (our development team uses it at my work).  There’s almost an expectation now that one is adding in 3rd party dependencies via Maven.  So, I’ve spent a little time this week reading up on Maven and the glory of POM files.

So, I have coded all of this up, including the beginnings of a simple object model for user data, and have been able to pull in the friend status data from Twitter and verify that my object model is being instatiated and populated correctly.  The next step is to get OAUTH working correctly as a precursor to deploying this client as a service, where a user could delegate authorization to my service to retrieve account data for the purposes of creating a pattern matching profile.  Although it looks to be a little dated, this OAUTH tutorial has been useful.  More on OAUTH in my next post.