Services are provided to support the management of the nodes used to model files and folders in the repository. The services provide methods to create and update nodes and define the relationships between them.

The operations supported by the File Folders service include:

Alfresco's version management is designed to manage versions of individual content nodes. To enable the versioning behavior, the versionable aspect must be applied to the node.

The Versioning services include the following capabilities:

Each version has a version number, which is allocated on a sequential basis and follows a similar strategy to Concurrent Versions System (CVS) version numbering. Generally, this version number is only used internally; the version label is used publicly to identify the version.

The version label is calculated from the version number and gives, within the scope of the version history, a unique label for the version. This label is placed in the versionable aspect to indicate the related current version for a node.

You can customize the generation of the version label by creating a version label policy behavior and registering it in place of the default version label policy. This gives applications flexibility to determine their own version-labeling policies. The default version label policy uses the 1.1, 1.2 style of progressive version labels, moving to 2.0 if the version is considered a major change. This is indicated in the version metadata to which the version label policy has access.

Check Out and Check In services are provided to control updates to document and prevent unwanted overwrites. When you check out a document, the document is locked, thus preventing other users writing changes to it. Alfresco uses an exclusive locking model that allows only one user to have a particular document checked out (locked) at any time. The user or application can unlock the document by either checking in the document or canceling the checkout.

You can use Check Out and Check In with or without versioning. If versioning is not enabled on a node (the versionable aspect is not present on the node), the check in overwrites the existing node and releases the lock unless the keepCheckedOut flag is used. With versioning enabled on the node, a new version is always created.

The Audit service provides a configurable record of actions and events. The information is stored in a database in a form that is designed to be simple for third-party reporting tools to consume.

The capabilities provided by the Audit service include:

A number of services are provided to support creating and updating user and group (authorities) information, authenticating users, and defining the actions that users can perform against nodes.

These services are:

See Chapter 6 for more detail on these services.

The content repository uses the repository Data Dictionary to manage definitions for content models such as folders, files, and metadata schemes. The content models are registered with the content repository to constrain the structure of nodes and the relationships between them, as well as to constrain property values. A Dictionary service is provided to allow access to the content models and provide a range of methods for querying and inspecting the model definitions.

See Chapter 5 for detailed information on working with content models.

The Search service provides methods for querying the repository and returning a filtered collection of nodes based on the user's permission. A number of search languages are available, including the following:

See the "Content Management Interoperability Services" section later in this chapter for more detail on CMIS and CMIS QL.

Content services provide advanced content management capabilities to automate tasks, handle format conversions, automatically extract content metadata, and generate thumbnails and proxies.

Control services provide the ability to manage workflow, Web projects, sandboxes, and assets.

Collaboration services provide the ability to manage sites, user and group membership, activities, tagging, and comments.

Embedded APIs are used by custom extensions executed directly against the Content Application Server. There are three main embedded APIs: the Alfresco Java Foundation API, the JavaScript API, and the Template API.

The JavaScript and Template APIs are the key building blocks for Web scripts, which are used to develop the RESTful APIs.

The following code samples illustrate usage of the embedded APIs.

The following example uses the Java API to create new content:

/**
 * Creates a new content node setting the content provided.
 *
 * @param  parent   the parent node reference
 * @param  name     the name of the newly created content object
 * @param  text     the content text to be set on the newly created node
 * @return NodeRef  node reference to the newly created content node
 *
private NodeRef createContentNode(NodeRef parent, String name, String text)
    {
        // Create a map to contain the values of the properties of the node
        Map<QName, Serializable> props = new HashMap<QName, Serializable>(1);
        props.put(ContentModel.PROP_NAME, name);

// use the node service to create a new node
        NodeRef node = this.nodeService.createNode(
                   parent,
                   ContentModel.ASSOC_CONTAINS,
                   QName.createQName(NamespaceService.CONTENT_MODEL_1_0_URI, name),
                   ContentModel.TYPE_CONTENT,
                   props).getChildRef();

        // Use the content service to set the content onto the newly created node
        ContentWriter writer = this.contentService.getWriter(node,
        ContentModel.PROP_CONTENT, true);
        writer.setMimetype(MimetypeMap.MIMETYPE_TEXT_PLAIN);
        writer.setEncoding("UTF-8");
        writer.putContent(text);

        // Return a node reference to the newly created node
        return node;
    }

Code Snippet: createContentNode.java

This example uses the Java API and the NodeService and ContentService to create a content node including both content and metadata. It takes a nodeRef of the folder that will contain the node, a string to be used for the nodes name, and a string containing the content. A map of the metadata data values is then created, which is passed as a parameter to the NodeServer that creates the node itself. The content is written to the node using the ContentService and finally the node reference for the newly created node is returned.

This second example uses the JavaScript API to create new content:

// create file in the user's home folder
var doc = userhome.createFile("myDoc.txt");
doc.content = "This is some content.";
doc.save();

Code Snippet: createfile.js

In this example a new document called myDoc.txt is created in the home space of the current user. The content for the new document is set to doc.content and the document is saved to commit our changes.

The final example uses the Template API to display all the properties for a given document:

<table>
 <#-- Get a list of all the property names for the document -->
 <#assign props = document.properties?keys>
 <#list props as t>
    <#-- If the property exists -->
    <#if document.properties[t]?exists>
       <#-- If it is a date, format it accordingly-->
       <#if document.properties[t]?is_date>

<tr><td>${t} = ${document.properties[t]?date}</td></tr>
       <#-- If it is a boolean, format it accordingly-->
       <#elseif document.properties[t]?is_boolean>
       <tr><td>${t} = ${document.properties[t]?string("yes", "no")}</td></tr>

       <#-- Otherwise treat it as a string -->
       <#else>
       <tr><td>${t} = ${document.properties[t]}</td></tr>
       </#if>
    </#if>
 </#list>
 </table>

Code Snippet: documentProperties.ftl

The template iterates over all the properties for a node called document and renders the values as appropriate for the data types returned.

There are several remote APIs available, allowing clients connecting from a separate tier to communicate with the Alfresco Content Application Server. These are based on Web services, and RESTful and CMIS protocols. The remote APIs are designed to be language agnostic, allowing development against these APIs using a range of development languages, including Java, PHP, Ruby, .NET, and many more.

The following is an example of calling a RESTful API to retrieve the list of tags for a document:

http://localhost:8080/alfresco/service/api/node/workspace/SpacesStore/
97526d57-d1ce-4578-931d-0cc48ff23602/tags

This will retrieve all the tags for the node with the node reference workspace: //SpacesStore/97526d57-d1ce-4578-931d-0cc48ff23602 in the body of the HTTP response, formatted in JSON. For example:

{
   "data" : ["tagOne", "tagTwo"]
}

Alfresco uses the Spring framework to implement an extremely modular architecture. Services are bound together through their interfaces and configured using Spring's declarative Dependency Injection. This allows existing services to be configured, extended, and replaced, and new services to be introduced.

The specific details vary from service to service. For example, it is possible to define new transformers by extending the baseContentTransformer. This defines how the new transformer is invoked, the source and target MIME types it supports, and the transformer's availability. This is done through configuration that extends the existing service. The underlying service itself does not need to be modified and no additional code is required.

The following example shows the Spring configuration required to extended the out-of-the-box RuntimeExecutableContentTransformer. This is a standard transformer that is able to execute system executables. An example of a command line transformation program is HTML Tidy (http://tidy.sourceforge.net/), which can transform HTML documents into XHTML documents.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/
dtd/spring-beans.dtd'>

<beans>
   <bean id="transformer.Tidy.XHTML" class="org.alfresco.repo.content.transform.
   RuntimeExecutableContentTransformer" parent="baseContentTransformer">
      <property name="checkCommand">
         <bean class="org.alfresco.util.exec.RuntimeExec">
            <property name="commandMap">
                <map>
                    <entry key=".*">
                        <value>tidy -help</value>
                    </entry>
                </map>
            </property>
            <property name="errorCodes">
               <value>2</value>
            </property>
         </bean>
      </property>
      <property name="transformCommand">
         <bean class="org.alfresco.util.exec.RuntimeExec">
            <property name="commandMap">
                <map>
                    <entry key="Linux">
                        <value>tidy -asxhtml -o '${target}' '${source}'</value>
                    </entry>
                    <entry key="Windows.*">
                        <value>tidy -asxhtml -o "${target}" "${source}"</value>
                    </entry>
                </map>
            </property>
            <property name="errorCodes">
               <value>2</value>
            </property>
         </bean>
      </property>
      <property name="explicitTransformations">

<list>
            <bean class="org.alfresco.repo.content.transform.
            ExplictTransformationDetails" >
                <property name="sourceMimetype"><value>text/html</value></property>
                <property name="targetMimetype"><value>application/xhtml+xml
                </value></property>
            </bean>
         </list>
      </property>
   </bean>
</beans>

Code snippet: tidyTransformer.xml

The actual transformation command used is defined in the transformCommand property. The transformation mechanism performs substitutions of the variables ${source} and ${target}, which are the full file paths of the source and target files for the transformation. For example:

tidy -asxhtml -o "${target}" "${source}"

The transformer comes with an optional feature, checkCommand, which is executed by the init method. If an error occurs during execution of this command, which cannot take any parameters, then the transformer is flagged as not available. When not available, the getReliability method will always return 0.0; otherwise it is assumed that the transformation command will be successful. The reliability of the transformation is used by the transformation registry to select the most appropriate transformer for a given transformation. The transformer remains directly usable—you can directly select it as an action to perform.

External utilities stick to a rough convention regarding the return codes. In this case, tidy returns a code value 2. The errorCodes property defines a comma separated list of values indicating failure; the default is "1, 2".

The final piece of configuration defines the MIME types that this transformer supports via the explicitTransformations property. In this case, the transformer supports a source MIME type of text/html and a target MIME type of application/xhtml+xml.

This example illustrates how to extend an existing service via configuration only: it has been possible to add a new transformer without any code changes. To complete the example, additional configuration is needed to expose the new transformer via the client interfaces or as a repository action. See Chapter 14 for more details.

The following section walks through an example of building a new service by showing the high-level interfaces for each tier of the service. To simply the example, the full detail of some of the methods will not be shown.

This example can be considered as a new content application service built on the Content Repository Services.

The example service provides a counter with methods for creating, listing, incrementing, decrementing, and resetting integer counter instances and their values. The counter can be used to persist how many times a particular event has occurred. For example, to generate a unique reference number for a document, the counter can be used to generate an integer that can be used as the basis of the reference number.

The service will implemented using the three tier approach described earlier in this chapter. Java will be used to provide underlying methods in Tier 1; the JavaScript API is used for Tier 2 to provide higher-level methods, allowing the counter to be called via repository actions and exposed via Tier 3 as the new RESTful counter API.

public interface CounterService
// Low level services for creating and updating counters.
{
    public enum CounterOperation { INC, DEC };

    // Create a counter and set the initial value.
    // Returns the counter id.
    String createCounter(int initialValue);

    // Get the value of a counter.
    int getCounterValue(counterId);

    // Update the counter value by a given step.  The counter operation
    // is provided.
    int updateCounterValue(String counterId, CounterOperation operation, int step);

    // Delete the counter.
    int deleteCounter();
}

// Create counter.  Initial value and default step are optional parameters.
// Returns the created counter object
function createCounter(initialValue=1, defaultStep=1);

// Get counter.
// Returns the counter object
function getCounter(counterId);

Counter
{
   var id;
   var defaultStep;
   var value;

   function increment(value=0);

   function decrement(value=0);

   function delete();
}

Method: GET /alfresco/counters
   Description: Returns a list of counters

   Example output:

   {
      "counters":
      {
         "counter0":
         {
            "id" : "counter0",
            "value" : 12,
            "url" : "/counters/counter0"
         },

 "counter1":

{
            "id" : "counter1",
            "value" : 3,
            "url" : "/counters/counter1"
         }
      }
   }

Method: POST /alfresco/counters
   Description: Creates a new counter

   Example input:
   {
      "id" : "counter2",
      "initialValue" : 0,
      "defaultStep" : 1
   }

   Example output:

   {
      "id" : "counter2",
      "value" : 0,
      "url" : "/counters/counter2"
   }

Method: GET /alfresco/counters/{counter-id}
   Description: Gets the current value for a counter

   Example output:

   {
      "id" : "counter2",
      "value" : 0,
      "url" : "/counters/counter2"
   }

Method - POST /alfresco/counters/{counter-id}
   Description: Increments or decrements a counter's value according to the passed
   in step value.

   Example input:

   {
      "step" : 1
   }

   Example output where existing value is 11:

   {
      "id" : "counter0",
      "value" : 12,
      "url" : "/counters/counter0"
   }

Method - DELETE /alfresco/counters/{counter-id}
   Description: Deletes the counter

Many large organizations today run multiple Enterprise content management systems, each with millions of dollars of implementation and integration on top of those systems that are specific to each underlying repository. Yet each system usually remains a silo of information that does not share content. In addition, an application built to a system cannot be used on another system. The lack of integration and interoperability means that organizations using multiple systems cannot get a consistent view of information. This creates substantial operational and compliance risks in that content cannot be found and consistently managed. The challenge is even greater for independent application vendors who create content management application solutions. Supporting more than one content management system can be a very expensive proposition.

CMIS promises to be a standard that provides interoperability where others have not. CMIS focuses on a few use cases and on being able to map to existing systems rather than specify how those systems should work. It is particularly important for CMIS to work with major ECM systems with a large installed base of users and content. CMIS is designed to be language-independent and uses Web protocols to access the repositories. CMIS supports both SOAP and REST through the AtomPub protocol.

CMIS does a good job of mapping data modeling, query capabilities, and content functionality of basic content services of these underlying systems. Despite the relative commonality of these systems, the CMIS Technical Committee has tried to ensure that the functionality exposed can actually be implemented.

The core use cases targeted by CMIS are:

These core use cases drove requirements around query, authentication, security, versioning, change logs, and basic content operations.

Some of the applications not directly addressed by CMIS but that the Technical Committee intended to be built on CMIS are:

At the root of the CMIS model and services is a repository, which is an instance of the content management system and its store of metadata, content, and indexes. The repository is the end point to which all requests are directed. In the RESTful model, it is the root path of the resources being addressed in CMIS. The repository is capable of describing itself and its capabilities.

The core CMIS object model (see Figure 4-3) is not very different from the Alfresco object model minus the support of aspects. Like Alfresco, CMIS supports object types that define properties associated with each type. Each object has an object type, properties defined by that object type, and an object ID that uniquely identifies that object. Object types support inheritance and are sub-typed as Document object types and Folder object types. Document object types may have content streams to store and access binary data. Object types may also be related through Relationship object types.

Figure 4.3. FIGURE 4-3

A Policy object represents an administrative policy that can be enforced by a repository, such as a retention management policy. An Access Control List (ACL) is a type of Policy object. CMIS allows applications to create or apply ACLs. The Alfresco repository also uses Policy objects to apply aspects.

Document objects have properties and content streams for accessing the binary information that is the document, properties that may be multi-valued, and versions (see Figure 4-4). Document objects can also have Renditions that represent alternate file types of the document. Only one Rendition type, a Thumbnail, is well defined.

Figure 4.4. FIGURE 4-4

Versioning in CMIS (see Figure 4-5) makes it relatively simple to encompass the various versioning models of different CMIS implementations. Each version is a separate object with its own object ID. For a given object ID, you can retrieve the specific version, the current version, or all versions of the object, as well as delete specific or all versions of a Document object. Document versions are accessed as a set of Document objects organized on the timestamp of the object. CMIS does not provide a history graph.

Figure 4.5. FIGURE 4-5

Document objects live in a folder hierarchy (see Figure 4-6). As in Alfresco, a folder can exist in another folder to create the hierarchy. The relationship between folder and document is many-to-many if the repository supports multifiling, allowing a document to appear in more than one folder. Otherwise, it is one-to-many.

Figure 4.6. FIGURE 4-6

A query in CMIS is based upon SQL-92 and should be familiar if you have used a relational database system like MySQL. The query itself is read-only and presents no data manipulation capabilities. The syntax consists of the following clauses:

The CMIS query maps the object type into a relational structure where object type approximates a table, the object approximates a row, and the property approximates a column that can be multivalued. The actual binary content can be queried using a full-text query and folder path information using the in_folder and in_tree functions. A query can also be paged for user interface presentation.

CMIS Services comprise Repository Change services, Navigation services, Object services, Multifiling (Folder) services, Discovery (Query) services, Versioning services, Relationship services, Policy services, and ACL services. You can access these services equally using SOAP or AtomPub, depending on your preferred architectural style. This book uses AtomPub and the RESTful style as an example of how to use CMIS with Alfresco.

Obviously, each CMIS service can become quite an involved topic in its own right. For a complete catalog of services, please see the CMIS specification on the OASIS Web site at www.oasis-open.org/committees/tc_home.php?wg_abbrev=cmis.

The Alfresco implementation is a thorough implementation of CMIS and has been the basis for many CMIS applications. Most applications that use CMIS with Alfresco use the AtomPub protocol over the SOAP protocol; however, some applications that have a strong Web services framework, like SAP and Tibco, use SOAP instead. In this book, examples are presented using the AtomPub protocol.

If you are programming CMIS applications in Java, you can use the Apache Abdera libraries, which were built to handle AtomPub. Abdera provides both client and server implementations of the Atom Publish and Subscribe protocols. You can find Apache Abdera at http://abdera.apache.org.

To use CMIS with PHP, it is best to use one of the PHP Web frameworks such as Drupal or Joomla. The Drupal interface was built by Optaros and Acquia and can be found at http://drupal.org/project/cmis.

CMIS is a good choice for building applications or application integrations against Alfresco when you wish to make the application portable to other systems; however, you will need to use Web scripts instead to:

You can also integrate Web scripts with the AtomPub protocol of CMIS.

For more information on using CMIS with Alfresco, including new Java bindings, visit http://cmis.alfresco.com. To access the CMIS specification, visit www.oasis-open.org/committees/cmis.