© 2008-2017 The original authors.

Note
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Preface

Project metadata

1. Working with Spring Stores

The goal of the Spring Content is to make it easy to create applications that manage content such as documents, images and video by significantly reducing the amount of boilerplate code that the Developer must create for themselves. Instead, the Developer provides interfaces only that declare the intent for the content-related functionality. Based on these, and on class-path dependencies, Spring Content is then able to inject storage-specific implementations.

Important

This chapter explains the core concepts and interfaces for Spring Content. The examples in this chapter use Java configuration and code samples for the Spring Content S3 module. Adapt the Java configuration and the types to be extended to the equivalents for the particular Spring Content module that you are using.

1.1. Core concepts

The central interfaces in the Spring Content are Store, AssociativeStore and ContentStore. These interfaces provide access to content streams through the standard Spring Resource API either directly or through association with Spring Data entities.

Example 1. ContentStore interface
public interface ContentStore<E, CID extends Serializable> {

	void setContent(E entity, InputStream content); 	(1)

	InputStream getContent(E entity);			(2)

	void unsetContent(E entity);				(3)
}
  1. Stores content and associates it with entity

  2. Returns the content associated with entity

  3. Deletes content and unassociates it from entity

For example, given an Entity User, a UserRepository and a ProfilePictureStore it is possible to associate and store a profile picture for each user.

Example 2. ContentStore interface
@Entity
@Data
public class User {
	@Id
	@GeneratedValue(strategy=GenerationType.AUTO)
	private Long id;

	private String username;

	@ContentId
	private String contentId;

	@ContentLength
	private Long contentLength
}

public interface UserRepository extends JpaRepository<User, Long> {
}

public interface ProfilePictureStore extends ContentStore<User, String> {
}

@SpringBootApplication
public class Application {
	public static void main(String[] args) {
		SpringApplication.run(Application.class, args);
	}

	@Bean
	public CommandLineRunner demo(UserRepository repository, ProfilePictureStore store) {
		return (args) -> {
			// create a new user
			User jbauer = new User("jbauer");

			// store profile picture
			store.setContent(jbauer, new FileInputStream("/tmp/jbauer.jpg"));

			// save the user
			repository.save(jbauer);
		};
	}
}

1.1.1. Using Stores with Multiple Spring Content Storage Modules

Using a single Spring Content storage module in your application keeps things simple because all Storage beans will use to that one Spring Content storage module as their implementation. Sometimes, applications require more than one Spring Content storage module. In such cases, a store definition must distinguish between storage technologies by extending one of the module-specific signature Store interfaces.

See Signature Types for the signature types for the storage modules you are using.

Manual Storage Override

Because Spring Content provides an abstraction over storage it is also common to use one storage module for testing but another for production. For these cases it is possible to again include multiple Spring Content storage modules, but use generic Store interfaces, rather than signature types, and instead specify the spring.content.storage.type.default=<storage_module_id> property to manually set the storage implementation to be injected into your Storage beans.

1.1.2. Events

Spring Content emits twelve events. Roughly speaking one for each Store method. They are:

  • BeforeGetResourceEvent

  • AfterGetResourceEvent

  • BeforeAssociateEvent

  • AfterAssociateEvent

  • BeforeUnassociateEvent

  • AfterUnassociateEvent

  • BeforeSetContent

  • AfterSetContent

  • BeforeGetContent

  • AfterGetContent

  • BeforeUnsetContent

  • AfterUnsetContent

Writing an ApplicationListener

If you wish to extend Spring Content’s functionality you can subclass the abstract class AbstractStoreEventListener and override the methods that you are interested in. When these events occur your handlers will be called.

There are two variants of each event handler. The first takes the entity with with the content is associated and is the source of the event. The second takes the event object. The latter can be useful, especially for events related to Store methods that return results to the caller.

Example 3. Entity-based AbstractContentRepositoryEventListener
public class ExampleEventListener extends AbstractContentRepositoryEventListener {

	@Override
	public void onAfterSetContent(Object entity) {
		...logic to inspect and handle the entity and it's content after it is stored
	}

	@Override
	public void onBeforeGetContent(BeforeGetContentEvent event) {
		...logic to inspect and handle the entity and it's content before it is fetched
	}
}

The down-side of this approach is that it does not filter events based on Entity.

Writing an Annotated StoreEventHandler

Another approach is to use an annotated handler, which does filter events based on Entity.

To declare a handler, create a POJO and annotate it as @StoreEventHandler. This tells Spring Content that this class needs to be inspected for handler methods. It iterates over the class’s methods and looks for annotations that correspond to the event. There are twelve handler annotations:

  • HandleBeforeGetResource

  • HandleAfterGetResource

  • HandleBeforeAssociate

  • HandleAfterAssociate

  • HandleBeforeUnassociate

  • HandleAfterUnassociate

  • HandleBeforeSetContent

  • HandleAfterSetContent

  • HandleBeforeGetContent

  • HandleAfterGetContent

  • HandleBeforeUnsetContent

  • HandleAfterUnsetContent

Example 4. Entity-based annotated event handler
@StoreEventHandler
public class ExampleAnnotatedEventListener {

	@HandleAfterSetContent
	public void handleAfterSetContent(SopDocument doc) {
		...type-safe handling logic for SopDocument's and their content after it is stored
	}

	@HandleBeforeGetContent
	public void onBeforeGetContent(Product product) {
		...type-safe handling logic for Product's and their content before it is fetched
	}
}

These handlers will be called only when the event originates from a matching entity.

As with the ApplicationListener event handler in some cases it is useful to handle the event. For example, when Store methods returns results to the caller.

Example 5. Event-based annotated event handler
@StoreEventHandler
public class ExampleAnnotatedEventListener {

	@HandleAfterSetContent
	public void handleAfterGetResource(AfterGetResourceEvent event) {
		SopDocument doc = event.getSource();
		Resource resourceToBeReturned = event.getResult();
		...code that manipulates the resource being returned...
	}
}

To register your event handler, either mark the class with one of Spring’s @Component stereotypes so it can be picked up by @SpringBootApplication or @ComponentScan. Or declare an instance of your annotated bean in your ApplicationContext.

Example 6. Handler registration
@Configuration
public class ContentStoreConfiguration {

	@Bean
	ExampeAnnotatedEventHandler exampleEventHandler() {
		return new ExampeAnnotatedEventHandler();
	}
}

1.1.3. Searchable Stores

Applications that handle documents and other media usually have search capabilities allowing relevant content to be found by looking inside of it for keywords or phrases, so called full-text search.

Spring Content is able to support this capability with it’s Searchable<CID> interface.

Example 7. Searchable interface
public interface Searchable<CID> {

    Iterable<T> search(String queryString);
}

Any Store interface can be made to extend Searchable<CID> in order to extend its capabilities to include the search(String queryString) method. For example:

public interface DocumentContentStore extends ContentStore<Document, UUID>, Searchable<UUID> {
}

...

@Autowired
private DocumentContentStore store;

Iterable<UUID> = store.search("to be or not to be");

For search to return actual results full-text indexing must be enabled. See Fulltext Indexing and Searching for more information on how to do this.

1.1.4. Renderable Stores

Applications that handle files and other media usually also have rendition capabilities allowing content to be transformed from one format to another.

Content stores can therefore optionally also be given rendition capabilities by extending the Renderable<E> interface.

Example 8. Renderable interface
public interface Renderable<E> {

	InputStream getRendition(E entity, String mimeType);
}

Returns a mimeType rendition of the content associated with entity.

Renditions must be enabled and renderers provided. See Renditions for more information on how to do this.

1.2. Creating Content Store Instances

To use these core concepts:

  1. Define a Spring Data entity and give it’s instances the ability to be associated with content by adding @ContentId and @ContentLength annotations

    @Entity
    public class SopDocument {
    	private @Id @GeneratedValue Long id;
    	private String title;
    	private String[] authors, keywords;
    
    	// Spring Content managed attribute
    	private @ContentId UUID contentId;
    	private @ContentLength Long contentLen;
    }
  2. Define an interface extending Spring Data’s CrudRepository and type it to the domain and ID classes.

    public interface SopDocumentRepository extends CrudRepository<SopDocument, Long> {
    }
  3. Define another interface extending ContentStore and type it to the domain and @ContentId class.

    public interface SopDocumentContentStore extends ContentStore<SopDocument, UUID> {
    }
  4. Optionally, make it extend Searchable

    public interface SopDocumentContentStore extends ContentStore<SopDocument, UUID>, Searchable<UUID> {
    }
  5. Optionally, make it extend Renderable

    public interface SopDocumentContentStore extends ContentStore<SopDocument, UUID>, Renderable<SopDocument> {
    }
  6. Set up Spring to create proxy instances for these two interfaces using JavaConfig:

    @EnableJpaRepositories
    @EnableS3Stores
    class Config {}
    Note
    The JPA and S3 namespaces are used in this example. If you are using the repository and content store abstractions for other databases and stores, you need to change this to the appropriate namespace declaration for your store module.
  7. Inject the repositories and use them

    @Component
    public class SomeClass {
    	@Autowired private SopDocumentRepository repo;
      	@Autowired private SopDocumentContentStore contentStore;
    
    	public void doSomething() {
    
    		SopDocument doc = new SopDocument();
    		doc.setTitle("example");
    		contentStore.setContent(doc, new ByteArrayInputStream("some interesting content".getBytes())); # (1)
    		doc.save();
    		...
    
    		InputStream content = contentStore.getContent(sopDocument);
    		...
    
    		List<SopDocument> docs = doc.findAllByContentId(contentStore.findKeyword("interesting"));
    		...
    
    	}
    }
    1. Spring Content will update the @ContentId and @ContentLength fields

1.3. Patterns of Content Association

Content can be associated with a Spring Data Entity in several ways.

1.3.1. Entity Association

The simplest, allowing you to associate one Entity with one Resource, is to decorate your Spring Data Entity with the Spring Content attributes.

The following example shows a Resource associated with an Entity Dvd.

@Entity
public class Dvd {
	private @Id @GeneratedValue Long id;
	private String title;

	// Spring Content managed attributes
	private @ContentId UUID contentId;
	private @ContentLength Long contentLen;

	...
}

public interface DvdRepository extends CrudRepository<Dvd, Long> {}

public interface DvdStore extends ContentStore<Dvd, UUID> {}

1.3.2. Property Association

Sometimes you might want to associate multiple different Resources with an Entity. To do this it is also possible to associate Resources with one or more Entity properties.

The following example shows two Resources associated with a Dvd entity. The first Resource is the Dvd’s cover Image and the second is the Dvd’s Stream.

@Entity
public class Dvd {
	private @Id @GeneratedValue Long id;
	private String title;

	@OneToOne(cascade = CascadeType.ALL)
	@JoinColumn(name = "image_id")
	private Image image;

	@OneToOne(cascade = CascadeType.ALL)
	@JoinColumn(name = "stream_id")
	private Stream stream;

	...
}

@Entity
public class Image {
	// Spring Data managed attribute
	private @Id @GeneratedValue Long id;

	@OneToOne
	private Dvd dvd;

	// Spring Content managed attributes
	private @ContentId UUID contentId;
	private @ContentLength Long contentLen;
}

@Entity
public class Stream {
	// Spring Data managed attribute
	private @Id @GeneratedValue Long id;

	@OneToOne
	private Dvd dvd;

	// Spring Content managed attributes
	private @ContentId UUID contentId;
	private @ContentLength Long contentLen;
}

public interface DvdRepository extends CrudRepository<Dvd, Long> {}

public interface ImageStore extends ContentStore<Image, UUID> {}

public interface StreamStore extends ContentStore<Stream, UUID> {}

Note how the Content attributes are placed on each property object of on the Entity itself.

When using JPA with a relational database these are typically (but not always) also Entity associations. However when using NoSQL databases like MongoDB that are capable of storing hierarchical data they are true property associations.

Property Collection Associations

In addition to associating many different types of Resource with a single Entity. It is also possible to associate one Entity with many Resources using a java.util.Collection property, as the following example shows.

@Entity
public class Dvd {
	private @Id @GeneratedValue Long id;
	private String title;

	@OneToMany
	@JoinColumn(name = "chapter_id")
	private List<Chapter> chapters;

	...
}

@Entity
public class Chapter {
	// Spring Data managed attribute
	private @Id @GeneratedValue Long id;

	// Spring Content managed attributes
	private @ContentId UUID contentId;
	private @ContentLength Long contentLen;
}

public interface DvdRepository extends CrudRepository<Dvd, Long> {}

public interface ChapterStore extends ContentStore<Chapter, UUID> {}

2. CMIS Integration

Spring Content CMIS supports the CMIS browser (JSON) bindings.

These bindings can be used as an alternative to the endpoints exported by Spring Content REST. This may be desirable for document management use cases or for migration away from traditional document management systems.

Spring Content CMIS provides a set of annotations that can be placed on an existing Spring Content domain model to map its classes onto the CMIS domain model in order to export its entities via the CMIS browser bindings.

2.1. CMIS Domain Model Mapping

2.1.1. CmisRepository

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 and is the root path of the resources being addressed in CMIS. With Spring Content CMIS, the repository is defined using the @EnableCmis annotation. Each Spring Content CMIS application therefore exports, at most, one CMIS Repository.

2.1.2. CmisObject

The Spring Data/Content domain model can be mapped to the CMIS domain model using two annotations; @CmisDocument and @CmisFolder. These annotations should be placed on Spring Data entity types with each being placed on a single entity type.

Both @CmisDocument and @CmisFolder inherit a common set of automatically mapped properties from a logical CmisObject, as follows:

Field CMIS field

@Id

cmis:objectId

@CreationDate

cmis:creationDate

@CreationBy

cmis:createdBy

@ModifiedDate

cmis:lastModificationDate

@ModifiedBy

cmis:lastModifiedBy

In addition, the @CmisName annotation must be present to identify the cmis:name field and the @CmisDescription annotation may be present to identify a cmis:description field.

2.1.3. CmisDocument

Entity types mapped to @CmisDocument that also have a ContentStore will also have additional content stream properties and service for accessing the binary information that is the document.

Field CMIS field

@ContentId

cmis:contentStreamId

@ContentLength

cmis:contentStreamLength

@MimeType

cmis:contentStreamMimeType

Entity types mapped to @CmisDocument that are managed with a Repository that extends LockingAndVersioningRepository have additional versioning properties and service.

Field CMIS field

@VersionNumber

cmis:versionLabel

@AncestorRootId

cmis:versionSeriesId

@LockOwner

cmis:versionSeriesCheckedOutBy

@VersionLabel

cmis:checkinComment

Other version-related cmis properties, like cmis:isLatestVersion for example, are computed at runtime. Private working copies (CMIS 1.1) are supported by default.

Currently, renditions and fulltext indexing/query are not supported.

2.1.4. CmisFolder

With a CMIS repository, Document objects can live in one, or more, folders. A folder can also exist in other folders creating a hierarchy.

Spring Content CMIS supports folder hierarchy by mapping an entity type to @CmisFolder and by mapping the parent/child relationship using the @CmisReference annotation. However, Spring Content CMIS support single-filing of documents and folders only. In JPA terms, it supports a bi-directional @OneToMany relationship between the folder and the document entity.

2.1.5. CmisNavigationService

These two annotations are sufficient to achieve a working folder hierarchy. However, it is also possible to provide a CmisNavigationService bean through configuration in order to provide a more efficient implementation for navigation. This is recommended.

2.2. CMIS Workbench

A good option for testing is to use the CMIS Workbench. If you wish to use this client application in your Spring application ensure you disable Spring’s hidden method filter otherwise it attempts to parse POSTed requests from the CMIS Workbench client causing the request to fail.

Put this line in your application.properties:

spring.mvc.hiddenmethod.filter.enabled=false

2.3. Using Spring Content CMIS

2.3.1. Enabling the CMIS Integration

To enable CMIS, place a @EnableCmis annotation on a suitable @Configuration class.

Example 9. Spring Content CMIS using Java Config
@Configuration
@EnableCmis(basePackages = "examples.acme",							(1)
		id = "1",													(2)
		name = "Example CMIS Integration",
		description = "Spring Content CMIS Integration Example",
		vendorName = "Spring Content",
		productName = "Spring Content Integration CMIS",
		productVersion = "1.0.0")
public static class ApplicationConfig {

	...beans...

}
  1. The packages to search for Spring Data Repositories and Spring Content Stores with entities that carry @CmisDocument and @CmisFolder annotations

  2. The id and other attribute of the Cmis Repository to export

2.3.2. Domain Model Mapping

CmisObject

In this example we have a superclass entity for the common properties shared between the @CmisDocument and @CmisFolder.

@Entity
@EntityListeners(AuditingEntityListener.class)
@Inheritance(strategy = InheritanceType.JOINED)
@NoArgsConstructor
@Getter
@Setter
public class BaseObject {

	@javax.persistence.Id									(1)
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private Long Id;

	@CmisName												(2)
	private String name;

	@CmisDescription										(3)
	private String description;

	@CreatedBy												(4)
	private String createdBy;

	@CreatedDate
	private Long createdDate;

	@LastModifiedBy
	private String lastModifiedBy;

	@LastModifiedDate
	private Long lastModifiedDate;

	@Version
	private Long vstamp;

	@CmisReference(type = CmisReferenceType.Parent)			(5)
	@ManyToOne(fetch = FetchType.LAZY, cascade = CascadeType.ALL)
	private Folder parent;

	public BaseObject(String name) {
		this.name = name;
	}
}
  1. Mapped to cmis:objectId

  2. Mapped to cmis:name

  3. Mapped to cmis:description

  4. Mapped to cmis:createdBy, cmis:creationDate, cmis:lastModifiedBy and cmis:lastModificationDate

  5. Maps the child end of a bi-directional one to many parent/child relationship

CmisFolder

Folder extends BaseObject and maps the only remaining folder-related attribute, the child end of the parent/child relationship.

@Entity
@NoArgsConstructor
@Getter
@Setter
@CmisFolder																				(1)
public class Folder extends BaseObject {

	@CmisReference(type= CmisReferenceType.Child)										(2)
	@OneToMany(fetch = FetchType.LAZY, mappedBy = "parent", cascade = CascadeType.ALL)
	private Collection<BaseObject> children;

	public Folder(String name) {
		super(name);
	}
}

public interface FolderRepository extends JpaRepository<Folder, Long> {
	List<Folder> findAllByParent(Folder parent);
}
  1. @CmisFolder indicating this should be exported as a cmis:folder type

  2. Maps the parent end of a bi-directional one to many parent/child relationship

CmisDocument

Document also extends BaseObject and also maps the content stream and version attributes.

@Entity
@NoArgsConstructor
@Getter
@Setter
@CmisDocument									(1)
public class Document extends BaseObject {

	@ContentId									(2)
	private UUID contentId;

	@ContentLength								(3)
	private Long contentLen;

	@MimeType									(4)
	private String mimeType;

	@LockOwner									(5)
	private String lockOwner;

	@AncestorId
	private Long ancestorId;

	@AncestorRootId								(6)
	private Long ancestralRootId;

	@SuccessorId
	private Long successorId;

	@VersionNumber
	private String versionNumber = "0.0";		(7)

	@VersionLabel
	private String versionLabel;				(8)

	public Document(String name) {
		super(name);
	}

	public Document(Document doc) {
		this.setName(doc.getName());
		this.setDescription(doc.getDescription());
		this.setParent(doc.getParent());
	}
}

public interface DocumentRepository extends JpaRepository<Document, Long>, LockingAndVersioningRepository<Document, Long> {
	List<Document> findAllByParent(Folder parent);
}


public interface DocumentStorage extends ContentStore<Document, UUID> {
	//
}
  1. @CmisDocument indicating this should be exported as a cmis:document type

  2. Mapped to cmis:contentStreamId

  3. Mapped to cmis:contentStreamLength

  4. Mapped to cmis:contentStreamMimeType

  5. Mapped to cmis:versionSeriesCheckedOutBy

  6. Mapped to cmis:versionSeriesId

  7. Mapped to cmis:versionLabel

  8. Mapped to cmis:checkinComment

CmisNavigationService

Optionally, you may also configure a CmisNavigationService bean in order to provide a more efficient implementation for navigation.

	@Bean
	public CmisNavigationService cmisNavigationService(FolderRepository folders, DocumentRepository docs) {

		return new CmisNavigationService<Folder>() {
			@Override
			public List getChildren(Folder parent) {
				List<Object> children = new ArrayList<>();
				List<Folder> folderChildern = folders.findAllByParent(parent);
				List<Document> documentChildren = docs.findAllByParent(parent);
				children.addAll(folderChildern);
				children.addAll(documentChildren);
				return children;
			}
		};
	}

For more information you can refer to our github example project here.