© 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 Modules

Using a unique Spring Content module in your application keeps things simple, because all Store interfaces are bound to the one Spring Content module. Sometimes, applications require using more than one Spring Content module. In such cases, a store definition must distinguish between storage technologies by extending one of the module-specific ContentStore interfaces.

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.1. Overview

When enabled, the Solr integration will forward all content to an Solr cluster for fulltext indexing.

2.2. Dependencies

Spring Content Solr requires a SolrClient bean that is used as the connection to the Solr cluster that you wish to use for indexing.

Solr is therefore enabled with following depedencies:

	<dependency>
		<groupId>org.apache.solr</groupId>
		<artifactId>solr-solrj</artifactId>
		<version>7.2.1</version>                (1)
		<exclusions>
			<exclusion>
				<groupId>org.codehaus.woodstox</groupId>
				<artifactId>wstx-asl</artifactId>
			</exclusion>
			<exclusion>
				<artifactId>log4j</artifactId>
				<groupId>log4j</groupId>
			</exclusion>
		</exclusions>
	</dependency>
  1. Specify the version that matches your Solr server. NB: as Spring Content certifies against the latest version, the version must be compatible with this.

And the following Java Config:

Example 9. Enabling Spring Content Solr with Java Config
@Configuration
@EnableFullTextSolrIndexing                 (1)
@EnableFilesystemStores                     (2)
public static class ApplicationConfig {

    @Bean                                   (3)
    public SolrClient solrClient() {
        return new HttpSolrClient.Builder("http://localhost:8983/solr/solr").build();
    }

}
  1. Specify the @EnableFullTextSolrIndexing annotation in an @Configuration class

  2. Spring Content Solr works with any Spring Content Storage Module

  3. Ensure a (SolrJ) SolrClient @Bean is instantiated somewhere within your @Configuration

2.3. When your Solr cluster is secured with Basic Authentication

If required, credentials can be specified using the following configuration properties.

Property Description

solr.username

Solr user

solr.password

Solr user’s password

2.4. Making Stores Searchable

With fulltext-indexing enabled, Store interfaces can be made Searchable. See Searchable Stores for more information on how to do this.

2.5. Taking control of the indexing process

When you @EnableFullTextSolrIndexing a store event handler is registered that intercepts content being added to a Store and sends that content to your Solr instance for full-text indexing. This is usually all you need. However, sometimes you may need more control over when documents are indexed. For these cases you can use the IndexService bean directly in your code to index (or unindex) content as required.

2.6. Indexing additional attributes

By default Spring Content Solr indexes content only. However, it is common to index additional attributes (from the primary domain model) that can then be used for filtering subsequent full-text queries or for efficiently populating search results (removing the need to perform additional queries against the primary domain model).

Add a bean that implements AttributeProvider to your application’s configuration:

    @Bean
    public AttributeProvider<Document> attributeProvider() {
        return new AttributeProvider<Document>() {

            @Override
            public Map<String, String> synchronize(Document entity) {

                Map<String, String> attrs = new HashMap<>();
                attrs.put("title", entity.getTitle());
                attrs.put("author", entity.getAuthor());
                return attrs;
            }
        };
    }

Whenever content is indexed this bean will be consulted providing an opportunity to provide the set additional attributes that you would like to be indexed.

To customize the query that gets executed when a Store’s Searchable method is invoked add a FilterQueryProvider bean to your application’s configuration:

    @Bean
    public FilterQueryProvider fqProvider() {
        return new FilterQueryProvider() {

            @Override
            public String[] filterQueries(Class<?> entity) {

                return new String[] {"author:foo@bar.com"};
            }
        };
    }
Note
this bean is often a request scoped bean or has an implementation based on a thread local variable in order to build and return filter queries based on the current execution context.

When fulltext queries are performed this bean will be consulted providing an opportunity to supplement the query with your own filters. These filters are often based on the additional attributes that have been indexed.

2.7. Search Return Types

Searchable is a generic type allowing you to specify the return type of the result set.

The simplest option is to type this interface to String in which case the result set will be a collection of the content IDs of content matching the search terms provided.

You can also type the interface to your own custom class. Several annotations are available allowing you to tailor full-text search results to your specific needs:

  • @ContentId; extracts the content ID of the content from your search results

  • @Highlight; extracts highlighted snippets from your search results so you can show users where the query matches are. Note that highlighters usually analyze the stored field value so you may have to ensure the field that your content is indexed into (usually _text_) is also a stored field.

  • Attribute; extracts the specified attribute from your search results (must be synchronized using an AttributeProvider)

The following example show a searchable ContentStore returning a custom type SearchResult.

    public interface DocumentStore
        extends ContentStore<Document, String>, Searchable<SearchResult> {
    }

    @Getter
    @Setter
    public static class SearchResult {

        @ContentId
        private String contentId;

        @Highlight
        private String highlight;

        @Attribute(name = "email")
        private String email;
    }