4.7. S-RAMP Implementation

The S-RAMP implementation strives to be a fully compliant reference implementation of the S-RAMP specification. This chapter describes the overall architecture of the implementation and also provides some information about how to configure it.
S-RAMP also provides a Java based client library that consumers can use to integrate their own applications with an S-RAMP compliant server.

4.7.1. S-RAMP Server

The server implementation is a conventional Java web application (WAR). The following technologies are used to provide the various components that make up the server implementation:
  • JCR (ModeShape): Used as the persistence engine, where all S-RAMP data is stored. Artifacts and ontologies are both stored as nodes in a JCR tree. All S-RAMP queries are mapped to JCRSQL2 queries for processing by the JCR API. The ModeShape JCR implementation is used by default. However, the persistence layer is pluggable allowing alternative providers to be implemented in the future.
  • AX-RS (RESTEasy): Used to provide the S-RAMP Atom based REST API. The S-RAMP specification documents an Atom based REST API that implementations must make available. The S-RAMP implementation uses JAX-RS (specifically RESTEasy) to expose all of the REST endpoints defined by the specification.
  • JAXB: Used to expose a Java data model based on the S-RAMP data structures defined by the specification (S-RAMP XSD schemas).

4.7.1.1. Configuring Server

You can configure the server by providing a configuration file to the server on startup. You can provide the configuration file in a number of ways:
  • sramp.properties: You can provide this external file in the JBoss application server's configuration directory. An alternative location is the home directory of the user running the application server.
  • custom external file: You can specify a custom location for the sramp.properties file by starting the application server with the sramp.config.file.name system property set. This is typically done using -Dsramp.config.file.name=<pathToFile> on the application server's command line startup script (often in JAVA_OPTS).
  • On the classpath: If no external file is found, you can use the classpath to lookup a default configuration.
The configuration file is a simple Java properties file, with the following properties available to be set: 
# The base URL of the S-RAMP server - can be useful in some advanced configurations where
# the incoming Request URL is not the canonical server address.
sramp.config.baseurl = http://host:port/context
# Turn on/off auditing of changes to S-RAMP artifacts
sramp.config.auditing.enabled = true
# Turn on/off auditing of changes to derived S-RAMP artifacts
sramp.config.auditing.enabled-derived = true

4.7.1.2. Extending Custom Deriver

Part of the S-RAMP specification is the concept of Derived content. This happens when an artifact of a certain type is added to the S-RAMP repository. The server is responsible for creating relevant derived artifacts from it. For example, when an XML Schema (XSD) document is added to the repository, the server is responsible for automatically creating an artifact for every top level Element, Complex Type, Simple Type, and Attribute declaration found in the XSD.
The S-RAMP implementation includes Artifact Derivers for all of the logical models defined by the S-RAMP specification (such as WSDL, XSD, Policy). However, it also provides a mechanism that allows users to provide Artifact Derivers for their own artifact types. This is done by performing the following steps:

Procedure 4.1. Task

  1. Write a custom Deriver Java class. It must implement ArtifactDeriver.
  2. Create a DeriverProvider (a class that implements DeriverProvider) used to map artifact types to implementations of ArtifactDeriver.
  3. Provide a text file named org.overlord.sramp.common.derived.DeriverProvider in the location META-INF/services. The content of this file must be a single line containing the fully qualified classname of the class defined in the previous step.
  4. Package everything into a JAR and make it available either on the classpath or in an external directory. Configure the external directory by setting property sramp.derivers.customDir.

4.7.2. S-RAMP Client

The S-RAMP Clients include the following:
  • S-RAMP Client Library (Jar)
  • S-RAMP Interactive Shell (CLI)
  • S-RAMP Browser (UI)
  • S-RAP+Maven Integration (maven wagon)
The S-RAMP Client Library is a Java client library implementing the S-RAMP Atom API. Other items in the list use the S-RAMP Client Library when connecting to the S-RAMP repository. This section describes how to use the S-RAMP Client Library.

4.7.2.1. S-RAMP Client Usage Examples

The S-RAMP client is a simple Java based client library and can be included in a Maven project by including the following pom.xml dependency: 
<dependency>
      <groupId>org.overlord.sramp</groupId>
      <artifactId>s-ramp-client</artifactId>
      <version>${sramp.client.version}</version>
</dependency>
Once the library is included in your project, you can use the client by instantiating the SrampAtomApiClient class. Note that the client class supports pluggable authentication mechanisms, although BASIC auth is just a matter of including the username and password upon construction of the client. For details, refer to the javadoc of the required class. Here are some usage examples to help you get started:
  • Upload an XSD document to S-RAMP 
    SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String artifactFileName = getXSDArtifactName();
InputStream is = getXSDArtifactContentStream();
ArtifactType type = ArtifactType.XsdDocument();
BaseArtifactType artifact = client.uploadArtifact(ArtifactType.XsdDocument(), is, artifactFileName);
  • Create a custom artifact in S-RAMP (meta-data only, no file content) 
    SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
ExtendedArtifactType artifact = new ExtendedArtifactType();
artifact.setArtifactType(BaseArtifactEnum.EXTENDED_ARTIFACT_TYPE);
artifact.setExtendedType("MyArtifactType");
artifact.setName("My Test Artifact #1");
artifact.setDescription("Description of my test artifact.");
BaseArtifactType createdArtifact = client.createArtifact(artifact);
  • Retrieve full meta-data for an XSD artifact by its UUID 
    SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String uuid = getArtifactUUID();
BaseArtifactType metaData = client.getArtifactMetaData(ArtifactType.XsdDocument(), uuid);
  • Retrieve artifact content 
    
SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String uuid = getArtifactUUID();
InputStream content = client.getArtifactContent(ArtifactType.XsdDocument(), uuid);
  • Query the S-RAMP repository (by artifact name) 
    SrampAtomApiClient client = new SrampAtomApiClient(urlToSramp);
String artifactName = getArtifactName();
QueryResultSet rset = client.buildQuery("/s-ramp/xsd/XsdDocument[@name = ?]")
        .parameter(artifactName)
        .count(10)
        .query();

4.7.2.2. Ontologies

The S-RAMP implementation provides an extension to the Atom based REST API to support management of ontologies. You can use any of the client's ontology related methods when communicating with the implementation of S-RAMP, however it is likely to fail when communicating with any other S-RAMP server. The S-RAMP client supports adding, updating, and getting (both individual and a full list) ontologies from the S-RAMP repository.

4.7.2.3. Auditing

The S-RAMP implementation offers an extension to the Atom based REST API to get and set auditing information for artifacts in the repository.

4.7.2.4. Custom Expander

A special feature of the S-RAMP client is the ability to automatically expand archive style artifacts (artifacts that are JARs, WARs, ZIPs, etc). This feature is similar to how the server creates Derived content. The result is that certain files from the archive being uploaded as an S-RAMP artifact are extracted from the archive and also uploaded to the server. When this happens, these expanded artifacts are added with an S-RAMP relationship (expandedFromDocument) that points to the archive artifact they were expanded from.
The S-RAMP implementation comes with a few built-in expanders (such as, java archive and SwitchYard archive). Additionally, custom expanders can be created and provided by implementing ZipToSrampArchiveProvider. In order to inform the S-RAMP client about the custom provider, you need to put it in a JAR along with a file named META-INF/services/org.overlord.sramp.atom.archive.expand.registry.ZipToSrampArchiveProvider. The contents of this file must be a single line with the fully qualified Java classname of the provider implementation.