Cream is a project mainly written in Java, it's free.
Java Content Repository module for Play! framework
h1. Cream module
A module that seamlessly integrates Apache Jackrabbit (JCR 2.0) with Play framework.
h2. Features
h2. Installation
Install locally this module
bc.. $ play install cream-{version}
p. Declare the proper dependency in conf/dependencies.yml
bc.. require:
p. and let Play download and install the dependencies
bc.. $ play deps
h2. Usage
p. Configure Cream in conf/application.conf
bc.. ## Cream module configuration cream.jcr.url=file://tmp-repo cream.jcr.username=admin cream.jcr.password=admin cream.jcr.workspace=default
%test.cream.jcr.mode=transient
p. Annotate your model classes and extend play.modules.cream.Model (not required but convenient). See jcrom and Play validation for further details.
bc.. @JcrNode(mixinTypes = { "mix:created", "mix:lastModified", "mix:referenceable" }) public class User extends Model {
@JcrName // this is the node name
@Required
public String name;
@JcrProperty
@Required
@Email
public String email;
@JcrProperty
@MinSize(5)
public String password;
...}
p. Note: model classes managed by Cream plugin must be annotated with @JcrNode (normally with at least mix:referenceable) but jcrom doesn't require it.
You need to open a Jcr session in order to access the model from the controllers. To achieve it you have these options:
bc.. public class MyController extends Controller { ... }
p. If you want to control session parameters (p.ex: the workspace), use @JcrSession
bc.. @JcrSession(workspace="myWorkspace") public class MyController extends Controller { ... }
p. 2) Inject a session in the Controller with @Inject
bc.. public class MyController extends Controller {
@Inject
static javax.jcr.Session jcrSession;
...}
p. 3) Do it manually
bc.. public void someMethod() { Session session = JCR.getSession(); try { ... } finally { session.logout(); } }
p. In some situations may be desirable that Cream didn't open a Jcr session for the invocation, use @JcrNoSession for that effect
bc.. @JcrNoSession public class MyController extends Controller { ... }
p. An example of Controller
bc.. public class MyController extends Controller {
...
public static void create(@Valid MyEntity entity) {
if (validation.hasErrors()) {
...
}
entity.create();
...
}
public static void index(Integer page) {
JcrQuery result = MyEntity.all();
List<MyEntity> entities = result.fetch(page, pageSize);
long totalNumOfEntities = result.count();
...}
... }
p. Note: if you don't specify a Jcr path for the entity, the simple class name will be used by default. If you need to save the entity in another path, set myEntity.path = "/mypath".
See cream/samples-and-test for more examples.
p. To use Cream with CRUD simply do nothing special
bc.. public class Users extends CRUD {
}
p. You can use Fixtures normally for your tests and initial data loading.
h3. Full Text Search
Jackrabbit is able to index binary content and text, of course. Jackrabbit text extractors
Full text search is achieved by the means of contains clause:
bc.. # 6.7.19 FullTextSearch (p 113) select from test where contains(name, 'hello -world') select from test where contains(name, $x) select from test as t where contains(t., 'hello -world') select * from test as t where contains([t].name, 'hello -world')
p. Score:
bc.. # 6.7.31 FullTextSearchScore (p 122) select from test where score()>4 select from test as x where score(x)<1
p. Result excerpts. Still not supported in Jackrabbit 2. However you can use the old syntax, for example:
bc.. // XXX see // http://jackrabbit.510166.n4.nabble.com/Use-of-excerpt-with-SQL2-td3249018.html // waiting for excerpt support with SQL-2 try { QueryManager qm = JCR.getQueryManager(); @SuppressWarnings("deprecation") Query q = qm.createQuery( "select excerpt(.) from nt:unstructured where jcr:path like '/mypath/%' and contains(., '"
p. For a pragmatic reference of SQL-2 take a look at the official Jackrabbit tests: Jackrabbit SQL-2 tests
h3. Repository Observers
To observe repository events create a class that implements javax.jcr.EventListener and annotate it with @JcrOnEvent. Cream will automatically register it for the current session.
bc.. @JcrOnEvent(eventTypes = Event.NODE_ADDED | Event.NODE_REMOVED | Event.PROPERTY_CHANGED, absPath = "/", isDeep = true) public class LoggingObserver implements EventListener {
@Override
public void onEvent(EventIterator events) {
while (events.hasNext()) {
Event event = events.nextEvent();
Logger.info("JcrEvent received: { %s }", event.toString());
}
}}
h3. Content Versioning
Make sure that "mix:versionable" mixin is set on the @JcrNode annotation of your entity:
bc.. @JcrNode(mixinTypes = { "mix:created", "mix:lastModified", "mix:versionable" }) public class MyVersionableEntity extends Model { ... }
p. The following properties are automatically available for your entity: String versionName, Date baseVersionCreated, Date versionCreated and boolean checkedout.
p. To obtain the version list for an instance of your versionable entity, make a call to @myEntity.getVersions()@.
p. To restore a version: @JcrVersionMapper.restoreVersionByUUID(yourEntityId, versionNameToRestore);@
p. To delete a version: @JcrVersionMapper.removeVersionByUUID(yourEntityId, versionName);@
p. Have fun!
h2. References
// and more to come...