If you have any comments, questions, or general-purpose harassment you would like give us about this book, then please use the comment form at the bottom of each page! We promise that we will try to incorporate any feedback you give (minus the profanity, of course), will respond to your questions, and credit you appropriately. I certainly hope that readers have not made the cheap joke that this is the first chapter with even a bit of content!

Although Nuxeo EP 5 is described as an "Enterprise Content Management system," none of our lessons to this point have dealt at all with the content of documents! We have showed you how to create a new document type, associated schemas with it, handle events, access control, etc. and not discussed at all how to read even one byte of content! Why? There are two reasons. The first, and probably less important, reason we have favored discussing properties rather than content is that most developers are familiar with the reading of bytes and manipulating them programmatically from a typical filesystem. Thus, the features of Nuxeo that involving manipulating a document's meta-data and presentation were likely to be more interesting to the reader. The second, and probably more important reason, we have favored discussing Nuxeo's property features over content is simple: content is a property.

One of the supplied schemas in Nuxeo is file. This schema has one property defined on it, the filename property. This is used, by convention, to store the filename of a file that has been imported into Nuxeo. The Nuxeo web UI follows this convention anytime you have the opportunity to "upload" a file. If you were to write a program that does a bulk import of files into Nuxeo you should follow this convention too, for example. Also by convention there is a property file:content that holds the bytes of a file that has been imported into Nuxeo. This is how "content" gets turned into a property. There is no rule that says that content must be stored on this property, but if you follow this convention your documents will work nicely with the web UI of Nuxeo. Finally, it should be clear by now that you may have multiple properties with "the content" on a Nuxeo document. There is no notion of a distinguished property that always has "the sole content" of a document. You might, for example, have a document that has multiple translations and the content of them living on properties like version_english and version_française.

public interface Blob {

    //how many bytes does the blob hold, if known
    long getLength();

    //cache the mime type
    String getMimeType();
    void setMimeType(String mimeType);

    //cache the digest (such as MD5 hash)
    String getDigest();
    void setDigest(String digest);

    //cache the originating filename
    String getFilename();
    void setFilename(String filename);

    //read content in various formats
    InputStream getStream() throws IOException;
    Reader getReader() throws IOException;
    byte[] getByteArray() throws IOException;
    String getString() throws IOException;

    //bulk transfer the entire blob content to various types of output
    void transferTo(OutputStream out) throws IOException;
    void transferTo(Writer out) throws IOException;
    void transferTo(File file) throws IOException;
}

We have brought up the subject of content because in this lesson we will be creating relations between documents (see below) if and only if the documents are photos. A document's "mime type" is a string like "image/jpeg". The part before the slash indicating the main, or content, type of the document and the part after the slash indicating more specific information about the format of the content, or its subtype. For example, the MP3 files that contain your music typically have the mime type "audio/mp3" and web pages are written, at least normally, using "text/html". When we do not know, or can't figure out, a document's mime type we use the mime type "application/octet" which should be interpreted as "bunch of bytes we don't know the format of." A complete list of mime types is hard to write because various programs and developers are constantly creating new ones; however, the Internet Assigned Numbers Authority (IANA) periodically makes a significant list available.

Although some systems use the filename to determine the mime type of an object with simple rules, such as all files that end with ".mp3" have mime type "audio/mp3", a more reliable method is to actually interogate the content itself. There are various libraries available that know where to probe a file to see what mime type it is. These libraries work by knowing things of the form "files of type audio/mp3 always have a byte with content 0 at the 421st position and a byte with content 255 at the 97th position in the file."

Nuxeo, naturually, provides a service that implements this functionality, the MimeTypeRegistry. You access this service in the normal way, with Framework.getService(MimetypeRegistry.class). Once you have a reference to the registry, a block of code like the following can be used to determine (or at least try to determine) the mime type of a DocumentModel that you expect has the file schema associated with it:

    protected String mimeTypeOfFileDocument(CoreSession session,
            DocumentModel documentModel) throws Exception {
        String filename = (String) documentModel.getProperty("file", "filename");
        if (filename == null) {
            return "application/octet";
        }
        MimetypeRegistry registry = Framework.getService(MimetypeRegistry.class);
        // this just gets the blob from the default place that the UI puts it
        Blob content = (Blob) documentModel.getProperty("file", "content");
        if (content == null) {
            return "application/octet";
        }
        String type = registry.getMimetypeFromStreamWithDefault(
                content.getStream(), "application/octet");
        log.info("Found mime type of " + documentModel.getPathAsString()
                + " is " + type);
        return type;
    }

The previous two topics, content and mime types, have been brought in so that we can discuss photos about events. In particular, we are going to improve our code for handling the event that a new document has been created. The goal is to allow members of our special group of "social directors" to add photos about events, they are type of people who would do this! These photos can be taken before the event, as a preview and to encourage participation in the upcoming event, or they can be taken after and are considered photos taken at the event. Here is the set of rules we would like to encode, more specifically.

Create a relation between a new document D and an upcoming event if:

A relation in Nuxeo is a triple, or tuple, of three items. This triple is usually written as (SUBJECT, VERB, OBJECT). These relations allow two documents, the SUBJECT and OBJECT that would otherwise be considered quite distict to show they are, well... "related" by the VERB. If the verb were something like "is translation of" then you can assume that the original content is the subject document and the translation is the object document. You can create these relations by hand using the Nuxeo EP 5 web UI with the "Relations" tab that is shown when you examine a document in detail, as is highlighted in this screen capture:

You can see in the darker portion of the screen capture, that the author is creating a relation between a document called "Bowie With Cigarette" and another document in the repository that will be found via search. The type of relation is shown in the Predicate field (fancier than saying plain old "Verb" field!). Nuxeo ships with a set of 5 basic predicates including the "Is based on" above. The other four are "conforms to," "references," "replaces," and "requires."

If you are interested in adding to or changing the set of relations that are shown in the annotations tab, you will need to look at the Nuxeo source code and then rebuild the Nuxeo server. This type of change is why we are open source! The Nuxeo source has a bundle called nuxeo-platform-relations-default-config. This bundle has a directory that defines the default set of relations. This bundle has two files in (of course!) in src/main/resources/directories that define the relations and their inverses - the inverse of a relation being the way of expressing that a document is the OBJECT of the relation. These two files reference, of course labels like label.relation.predicate.References that are then translated to the user's preferred language. These, just as in our previous lesson, end up being referred to by messages_en.properties or similar files for other languages; for the default installation these can be found in the Nuxeo source code, in the bundle nuxeo-platform-lang in the src/main/resources/nuxeo.war/WEB-INF/classes directory. We hope that this continues to hammer home the point that your bundles and Nuxeo's bundles work in the same manner.

12.4.1. Nuxeo's internal relations

Although Nuxeo exposes the relations tab, as shown above, those are the relations it expects users to create "by hand." There are two built-in "features" of Nuxeo that are actually just some user interface candy that hide relations. First, the Nuxeo comment system is implemented using relations. When you use the UI to create a comment, like "This is an example" in the snap above, the Nuxeo comment system swings into action. It creates a new document, stores the contents of the comment in property and then creates a relation between the new document and the one the comment is related to. Then, when it displays the user interface for a document, it is easy to find the comments on the document being displayed since the pointers (relations) are already in place.

Note

We hope it comes as no surprise to you that the Nuxeo comment system defines a new schema type (in a file called comment.xsd!) with some fields in it like comment, author, and creationTime. Further, the comment system uses an event listener to become informed about documents getting deleted. It uses this event to delete comment documents when the document they are associated with gets removed. The only part of the comment system that uses parts of the API we have not yet covered is the User Interface presented on the comments tab. You could build most of the Nuxeo comment system with the lessons you have had to this point! Nuxeo has no magic.

The other feature that makes use of relations is Nuxeo is the annotation system that was released with version 5.2 of Nuxeo EP. This system allows you to select regions of a document - either an rectangular region of an image document or some text from the document - and associate an annotation with it. Just as a comment is a subject document with a relation to the whole of an object document, an annotation is a subject document with a relation to a part of an object document. When you display an image, for example, Nuxeo's annotation system uses the relations to display an image like this:

As you can see in the image above, Nuxeo knows which part of the original image is the source of the annotation and the text that was originally entered as the annotation itself is displayed in the box to the side. (This image is from the Inauguration of President Obama, the person pictured is Chief Justice John Roberts, who goofed up his lines for the presidential oath of office.)

Nuxeo tries very hard to follow standards. With any relation, we use the RDF standard for storing/accessing relations and we use a popular (if not standard) way of programming to the RDF standard with Jena. For annotations, Nuxeo is one of the earliest implementations of the (still maturing) Annotea standard for annotating documents. Again, this standard is part of the work going on as part of the Semantic Web project at the W3C in an effort to make the web "make sense" for machines.

We have revamped the now somewhat busy DocumentCreationListener class to include a few new or refactored functions. One of these is the "middleman" that when given a new document, model, it checks to see if any event is "related" to it:

    private void checkDocumentForRelationToEvent(DocumentEventContext context,
            DocumentModel model) throws Exception {
        RelationHelper helper = new RelationHelper();
        CoreSession session = context.getCoreSession();
        log.info("Checking document for relation:" + model.getPathAsString());
        DocumentModel eventDoc = helper.isEventImage(session, model);
        if (eventDoc != null) {
            createBasicRelation(model, eventDoc, false);
        }
        eventDoc = helper.isPreviewImage(session, model);
        if (eventDoc != null) {
            createBasicRelation(model, eventDoc, true);
        }
        session.save();
    }

This method is straightforward most areas. First we create an instance of RelationHelper, a new class for the lesson, that implements the rules for adding an annotation we explained in the previous section. The helper has two methods, isEventImage and isPreviewImage, that implement the two different cases of photos from an event or images that are previews of the event. If the helper wants to indicated success, it return a DocumentModel that represents the Upcoming document that the new (photo) DocumentModel is related to. It returns null if no relations should be created.

So, this method should be called anytime a new document is created, to see if meets our criteria for being an image of the right kind and from a user in the right group. When this method wants to create a relation between two documents, it calls createBasicRelation, but to discuss that function we need to explain properties of relations.

    private void createBasicRelation(DocumentModel imageDocumentModel,
            DocumentModel eventDocumentModel, boolean isPreview)
            throws Exception {

        QNameResource imageAsResource = getDocumentResource(imageDocumentModel);
        QNameResource eventDocumentAsResource = getDocumentResource(eventDocumentModel);
        ResourceImpl predFwd, predRev;
        if (isPreview) {
            predFwd = new ResourceImpl(REFERENCES_URI);
            predRev = new ResourceImpl(REFERENCES_URI);
        } else {
            predFwd = new ResourceImpl(BASED_ON_URI);
            predRev = new ResourceImpl(BASED_ON_URI);
        }

        String commentText;
        if (isPreview) {
            commentText = "About the event";
        } else {
            commentText = "From the event";
        }

        Statement fwd = new StatementImpl(imageAsResource, predFwd,
                eventDocumentAsResource);
        setProperties(fwd, "[Automatically Added]", new Date(), commentText);

        Statement rev = new StatementImpl(eventDocumentAsResource, predRev,
                imageAsResource);
        setProperties(rev, "[Automatically Added]", new Date(), commentText);
        ArrayList<Statement> stmtList = new ArrayList<Statement>();
        stmtList.add(fwd);
        stmtList.add(rev);
        getRelationManager().add(DEFAULT, stmtList);
    }

12.5.2. Seeing relations in action

Since we have used relations that are understood by the Nuxeo EP 5 Web User Interface, the effects of our modified CreateDocumentListener and its new "helper" can be seen through your web browser. In the screen snap below, there has been an Upcoming document created by someone realted to an upcoming show by (some guy named) David Bowie. A member of the socialButterfiles group has helpfully added a two images to the repository to convince the (skeptical) masses to attend the concert by this unknown artist. The UI depicted in this snap is reached by clicking on the Relations tab of the Upcoming event:

The event document has two relations created for the incoming case (forward) and two for the reverse or outgoing case. It should be clear that the comments/author have been created by the method createBasicRelation above. Further, if you cilck on the links you will presented with the document that is the "other end" of the relation, in this case both photos that have been uploaded by one of the social directors.