© 2008-present 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
-
Version control - http://github.com/paulcwarren/spring-content/
-
Bugtracker - http://github.com/paulcwarren/spring-content/issues
-
Release repository - https://repo1.maven.org/maven2/
-
Snapshots repository - https://oss.sonatype.org/content/repositories/snapshots
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.
1.1.1. Store
The simplest interface is the Store
interface. Essentially, it is a Spring ResourceLoader
that returns instances Spring Resource
. It is also generic allowing the Resource’s ID (or location) to be specified. All other Store interfaces extend from Store
.
public interface Store<SID extends Serializable> {
Resource getResource(SID id); (1)
}
-
Returns a Resource handle for the specified
id
For example, given a PictureStore
that extends Store
it is possible to store (retrieve and delete) pictures.
1.1.2. AssociativeStore
AssociativeStore
extends from Store
allowing Spring Resource’s to be associated with JPA Entities.
public interface AssociativeStore<SID extends Serializable> {
Resource getResource(SID id); (1)
void associate(S entity, PropertyPath path, SID id); (2)
void unassociate(S entity, PropertyPath path); (3)
Resource getResource(S entity, PropertyPath path); (4)
}
-
Returns a Resource handle for the specified
id
-
Associates the Resource
id
with the Entityentity
at the PropertyPathpath
-
Unassociates the Resource at the PropertyPath
path
from the entity -
Returns a handle for the associated Resource at PropertyPath
path
For example, given an Entity User
with Spring Content annotations, a UserRepository
and the PictureStore
this time extending AssociativeStore
it is possible to store and associate a profile picture for each user.
@Entity
@Data
public class User {
@Id
@GeneratedValue(strategy=GenerationType.AUTO)
private Long id;
private String username;
@ContentId
private String profilePictureId;
@ContentLength
private Long profilePictureLength
}
public interface UserRepository extends JpaRepository<User, Long> {
}
public interface PictureStore extends AssociativeStore<User, String> {
}
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
@Bean
public CommandLineRunner demo(UserRespository repo, PictureStore store) {
return (args) -> {
// create a new user
User jbauer = new User("jbauer");
// store a picture
WritableResource r = (WritableResource)store.getResource("/some/picture.jpeg");
try (InputStream is = new FileInputStream("/tmp/jbauer.jpg")) {
try (OutputStream os = ((WritableResource)r).getOutputStream()) {
IOUtils.copyLarge(is, os);
}
}
// associate the Resource with the Entity
store.associate(jbauer, PropertyPath("profilePicture"), "/some/picture.jpeg");
// save the user
repository.save(jbauer);
};
}
}
1.2. ContentStore
ContentStore
extends AssociativeStore and provides a more convenient API for managing associated content based on java Stream
, rather than Resource
.
public interface ContentStore<E, CID extends Serializable> {
void setContent(E entity, InputStream content); (1)
InputStream getContent(E entity); (2)
void unsetContent(E entity); (3)
}
-
Stores content and associates it with
entity
-
Returns the content associated with
entity
-
Deletes content and unassociates it from
entity
The example above can be refactored as follows:
@Entity
@Data
public class User {
@Id
@GeneratedValue(strategy=GenerationType.AUTO)
private Long id;
private String username;
@ContentId
private String profilePictureId;
@ContentLength
private Long profilePictureLength
}
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, PropertyPath.from("profilePicture"), new FileInputStream("/tmp/jbauer.jpg"));
// save the user
repository.save(jbauer);
};
}
}
1.3. ReactiveContentStore
ReactiveContentStore
is an experimental Store that provides a reactive API for managing associated content based on
Mono and Flux reactive API.
public interface ReactiveContentStore<E, CID extends Serializable> {
Mono<S> setContent(S entity, PropertyPath path, long contentLen, Flux<ByteBuffer> buffer); (1)
Flux<ByteBuffer> getContentAsFlux(S entity, PropertyPath path); (2)
Mono<E> unsetContent(E entity); (3)
}
-
Stores content and associates it with
entity
-
Returns the content associated with
entity
-
Deletes content and unassociates it from
entity
The example above can be refactored as follows:
@Entity
@Data
public class User {
@Id
@GeneratedValue(strategy=GenerationType.AUTO)
private Long id;
private String username;
@ContentId
private String profilePictureId;
@ContentLength
private Long profilePictureLength
}
public interface UserRepository extends JpaRepository<User, Long> {
}
public interface ProfilePictureStore extends ReactiveContentStore<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
FileInputStream fis = new FileInputStream("/tmp/jbauer.jpg");
int len = fis.available();
ByteBuffer byteBuffer = ByteBuffer.allocate(len);
Channels.newChannel(fis).read(byteBuffer);
store.setContent(jbauer, PropertyPath.from("profilePicture"), len, Flux.just(byteBuffer)))
.doOnSuccess(updatedJbauer -> {
// save the user
repository.save(updatedJbauer).block(Duration.ofSeconds(10));
}).block(Duration.ofSeconds(10));
};
}
}
Currently, S3 is the only storage module that supports this experimental API.
1.3.1. Content Properties
As we can see above content is "associated" by adding additional metadata about the content to the Entity. This additional metadata is annotated with Spring Content annotations. There are several. The only mandatory annotation is @ContentId
. Other optional annotations include @ContentLength
, @MimeType
and @OriginalFileName
. These may be added to your entities when you need to capture this additional infomation about your associated content.
When adding these optional annotations it is highly recommended that you correlate the field’s name creating a "content property". This allows for multiple pieces of content to be associated with the same entity, as shown in the following example. When associating a single piece of content this is not necessary but still recommended.
@Entity
@Data
public class User {
@Id
@GeneratedValue(strategy=GenerationType.AUTO)
private Long id;
private String username;
@ContentId
private String profilePictureId; (1)
@ContentLength
private Long profilePictureLength
@MimeType
private String profilePictureType;
@OriginalFileName
private String profilePictureName;
@ContentId
private String avatarId; (2)
@ContentLength
private Long avatarLength
@MimeType
private String avatarType;
}
-
Content property "profilePicture" with id, length, type and original filename
-
Content property "avatar" with id, length and type
When modeled thus these can then be managed as follows:
InputStream profilePicture = store.getContent(user, PropertyPath.from("profilePicture"));
store.setContent(user, PropertyPath.from("avatar"), avatarStream);
1.3.2. Nested Content Properties
If desired content properties can also be nested, as the following JPA example shows:
@Entity
@Data
public class User {
@Id
@GeneratedValue(strategy=GenerationType.AUTO)
private Long id;
private String username;
private @Embedded Images images = new Images();
}
@Embeddable
public class Images {
@ContentId
private String profilePictureId;
@ContentLength
private Long profilePictureLength
@MimeType
private String profilePictureType;
@OriginalFileName
private String profileName;
@ContentId
private String avatarId;
@ContentLength
private Long avatarLength
@MimeType
private String avatarType;
}
These can then be managed with forward slash (/
) separated property paths:
InputStream profilePicture = store.getContent(user, PropertyPath.from("images/profilePicture"));
store.setContent(user, PropertyPath.from("images/avatar"), avatarStream);
1.3.3. 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.3.4. 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.
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
@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.
@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.
@Configuration
public class ContentStoreConfiguration {
@Bean
ExampeAnnotatedEventHandler exampleEventHandler() {
return new ExampeAnnotatedEventHandler();
}
}
1.3.5. 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.
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.3.6. 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.
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.4. Creating Content Store Instances
To use these core concepts:
-
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; }
-
Define an interface extending Spring Data’s
CrudRepository
and type it to the domain and ID classes.public interface SopDocumentRepository extends CrudRepository<SopDocument, Long> { }
-
Define another interface extending
ContentStore
and type it to the domain and@ContentId
class.public interface SopDocumentContentStore extends ContentStore<SopDocument, UUID> { }
-
Optionally, make it extend
Searchable
public interface SopDocumentContentStore extends ContentStore<SopDocument, UUID>, Searchable<UUID> { }
-
Optionally, make it extend
Renderable
public interface SopDocumentContentStore extends ContentStore<SopDocument, UUID>, Renderable<SopDocument> { }
-
Set up Spring to create proxy instances for these two interfaces using JavaConfig:
@EnableJpaRepositories @EnableS3Stores class Config {}
NoteThe 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. -
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")); ... } }
-
Spring Content will update the
@ContentId
and@ContentLength
fields
-
1.5. Patterns of Content Association
Content can be associated with a Spring Data Entity in several ways.
1.5.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.5.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. Azure Storage
2.1. Maven Central Coordinates
The maven coordinates for this Spring Content library are as follows:
<dependency>
<groupId>com.github.paulcwarren</groupId>
<artifactId>spring-content-azure-storage</artifactId>
</dependency>
As it is usual to use several Spring Content libraries together importing the bom is recommended:
<dependency>
<groupId>com.github.paulcwarren</groupId>
<artifactId>spring-content-bom</artifactId>
<version>${spring-content-version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
2.2. Annotation-based Configuration
Spring Content Azure Storage is enabled with the following Java Config.
@Configuration
@EnableAzureStorage
public static class ApplicationConfig {
@Value("#{environment.AZURE_STORAGE_ENDPOINT}")
private String endpoint;
@Value("#{environment.AZURE_STORAGE_CONNECTION_STRING}")
private String connString;
@Bean
public BlobServiceClientBuilder storage() {
return new BlobServiceClientBuilder()
.endpoint(endpoint)
.connectionString(connString);
}
}
2.3. Configuration Properties
The following configuration properties (prefix spring.content.azure
) are supported.
Property | Required | Description |
---|---|---|
bucket |
No |
Content store location. If not set as an application property Spring Content Azure Storage will look for the environment variable |
2.4. Accessing Content
2.4.1. Signature Types
Azure Storage supports the following signature types:
-
org.springframework.content.azure.store.AzureStorageContentStore
The module id for the spring.content.storage.type.default
property is azs
.
2.4.2. Storage Model
With Azure Blob Storage, buckets and objects are the two main primitives, where objects are stored in buckets. Azure has a flat structure with no hierarchy like you would see in a typical file system. There are also no limits to the number of buckets or objects in buckets.
2.4.3. Loading Spring Resources from a Store or AssociativeStore
When a Resource is loaded from the Store the following rules are used to determine the identify the BlobId
of the
object.
For a Store
, when a Resource is loaded using a call to getResource(ID location)
.
-
if the Store is typed to a
BlobId
this will be used as-is. -
otherwise, if a registered Spring Converter exists that converts from Store’s ID type to a
BlobId
this will be used to convert the location (specified in the call togetResource
) into an instance ofBlobId
-
otherwise, a
BlobId
is created from the default bucket and the location (specified in the call togetResource
).
For an AssociativeStore
(or indirectly a ContentStore
), when a Resource is loaded from a call to getResource(S entity)
:
-
if the store’s ID type is typed to a
BlobId
this will be used as-is -
otherwise, if a registered Spring Converter exists that converts the the Store’s entity (S) type to a
BlobId
this will be used to establish an instance ofBlobId
-
otherwise, if one of the Entity’s fields is annotated with
@Bucket
, the@ContentId
and the@Bucket
will be used as name and bucket respectively to create an instance ofBlobId
-
otherwise, the
@ContentId
field and default bucket will be used as name and bucket respectively to create an instance ofBlobId
See Configuring a Spring Converter for more information on how to register a converter.
2.4.4. Setting Content using a ContentStore
Storing content is achieved using the ContentStore.setContent(entity, InputStream)
method.
If content has not yet been stored with this entity and an Id has not been assigned one will be generated
based in java.util.UUID
.
The @ContentId
and @ContentLength
annotations will be updated on entity
.
If content has previously been stored it will overwritten updating just the @ContentLength attribute, if present.
2.4.5. Getting Content from a ContentStore
Content can be accessed using the ContentStore.getContent(entity)
method.
2.4.6. Unsetting Content from a ContentStore
Content can be removed using the ContentStore.unsetContent(entity)
method.
2.4.7. Configuring a Spring Converter
To configure Spring Content Azure Storage with one or more Spring Converters that convert your Entities, or IDs, to an instance of BlobId the following approach can be used:
@Configuration
public class AzureStoreConfiguration {
@Bean
public AzureStorageConfigurer configurer() {
return new AzureStorageConfigurer() {
@Override
public void configureAzureStorageConverters(ConverterRegistry registry) {
registry.addConverter(new Converter<TestEntity, BlobId>() {
@Override
public BlobId convert(TestEntity entity) {
return BlobId.of(entity.getCustomBucketField(), entity.getCustomContentIdField());
}
});
}
}
}
}
3. Indexing & Searching with Solr
3.1. Overview
When enabled the Solr integration will forward all content to Solr for fulltext indexing which can then be searched by adding the optional Searchable<CID>
interface to the Content Repositories.
3.2. Dependencies
Add the solrj to the classpath.
<dependency>
<groupId>org.apache.solr</groupId>
<artifactId>solr-solrj</artifactId>
<version>5.5.3</version> (1)
<exclusions>
<exclusion>
<groupId>org.codehaus.woodstox</groupId>
<artifactId>wstx-asl</artifactId>
</exclusion>
<exclusion>
<artifactId>log4j</artifactId>
<groupId>log4j</groupId>
</exclusion>
</exclusions>
</dependency>
-
If using Spring Boot the version may be omitted
3.3. Enabling
-
Specify the
@EnableFullTextSolrIndexing
annotation to your@Configuration
Spring Application block. -
Ensure a
(SolrJ) SolrClient
@Bean
is instantiated somewhere within your@Configuration
Spring Application block.
3.4. Configuring
By default when the Solr module is enabled Spring-Content looks for a http://localhost:8983/solr/solr
solr server with no username or password.
To change this behavior the following variables need to be set via the Externalized Configuration method.
Property | Description |
---|---|
solr.url |
Url of the Solr host (including port and core) |
solr.username |
Solr user |
solr.password |
Solr user’s password |