eXo JCR Developer Guide

Java Content Repository and Extension services

Copyright © 2009, 2010 eXoPlatform

I. eXoJCR
1. Introduction in eXoJCR
JCR (JSR-170) API main concepts
Data model
2. Why use JCR?
What is JCR?
Why use JCR?
What does eXo do?
Further Reading
3. eXo JCR Implementation
Related Documents
How it works
Workspace Data Model
4. Advantages of eXo JCR
Advantages for application developers:
Advantages for managers
5. Compatibility Levels
Introduction
Level 1
Level 2
Optional features
6. Using JCR
1 Using eXo JCR in an application
Obtaining a Repository object
JCR Session common considerations
JCR Application practices
Simplifying the management of a multi-workspace application
Reusing SessionProvider
7. JCR Extensions
JCR Service Extensions
Concept
Implementation
Configuration
Related Pages
8. eXo JCR Application Model
9. NodeType Registration
Interfaces and methods
ExtendedNodeTypeManager
NodeTypeValue
NodeDefinitionValue
PropertyDefinitionValue
ItemDefinitionValue
Node type registration
Run time registration from xml file.
Run time registration using NodeTypeValue.
Changing existing node type
Removing node type
Practical How to
Adding new PropertyDefinition
Adding new child NodeDefinition
Changing or removing existing PropertyDefinition or child NodeDefinition
Changing the list of super types
10. Registry Service
Concept
The API
Configuration
11. Namespace altering
Adding new namespace
Changing existing namespace
Removing existing namespace
12. Node Types and Namespaces
Introduction
Node Types definition
Namespaces definition
13. eXo JCR configuration
Related documents
Portal and Standalone configuration
JCR Configuration
Repository service configuration (JCR repositories configuration)
Repository configuration:
Workspace configuration:
Workspace data container configuration:
Value Storage plugin configuration (for data container):
Initializer configuration (optional):
Cache configuration:
Query Handler configuration:
Lock Manager configuration:
Help application to prohibit the use of closed sessions
14. Multilanguage support in eXo JCR RDB backend
Introduction
Oracle
DB2
MySQL
PostgreSQL
15. Search Configuration
XML Configuration
Configuration parameters
Global Search Index
Global Search Index Configuration
Customized Search Indexes and Analyzers
Creating the filter
Creating the analyzer
Creating the search index
Configuring your application to use your SearchIndex
Configure your application to use your Analyzer
Indexing Adjustments
IndexingConfiguration
Indexing rules
Node Scope Limit
Indexing Boost Value
Conditional Index Rules
Exclusion from the Node Scope Index
Indexing Aggregates
Property-Level Analyzers
Example
Characteristics of Node Scope Searches
Advanced features
16. JCR Configuration persister
Idea
Usage
17. JDBC Data Container Config
Introduction
Multi-database Configuration
Single-database configuration
Configuration without DataSource
Dynamic Workspace Creation
Simple and Complex queries
Forse Query Hints
Notes for Microsoft Windows users
18. External Value Storages
Introduction
Tree File Value Storage
Simple File Value Storage
Content Addressable Value storage (CAS) support
Disabling value storage
19. Workspace Data Container
20. REST Services on Groovy
Concept
Usage
21. Configuring JBoss AS with eXo JCR in cluster
Launching Cluster
Deploying eXo JCR to JBoss As
Configuring JCR to use external configuration
Requirements
Environment requirements
Configuration requirements
22. JBoss Cache configuration
JBoss cache configuration for indexer, lock manager and data container
JGroups configuration
Allow to share JBoss Cache instances
Shipped JBoss Cache configuration templates
Data container template
Lock manager template
Query handler (indexer) template
23. LockManager configuration
Introduction
LockManagerImpl
CacheableLockManagerImpl
Configuration
Simple JbossCache Configuration
Template JBossCache Configuration
Data Types in Different Databases
24. QueryHandler configuration
Indexing in clustered environment
Configuration
Query-handler configuration overview
Standalone strategy
Cluster-ready indexing strategies
Local Index Recovery Filters
JBoss-Cache template configuration
Asynchronous reindexing
On startup indexing
Hot Asynchronous Workspace Reindexing via JMX
Notices
Advanced tuning
Lucene tuning
25. JBossTransactionsService
Introduction
Configuration
26. TransactionManagerLookup
Configuration
27. RepositoryCreationService
Intro
Dependencies
How it works
Configuration
RepositoryCreationService Interface
Conclusions and restrictions
28. JCR Query Usecases
Intro
Query Lifecycle
Query Creation and Execution
Query Result Processing
Scoring
Query result settings
Type Constraints
Property Constraints
Path Constraint
Ordering specifing
Fulltext Search
Indexing rules and additional features
Query Examples
SetOffset and SetLimit
Common info
Repository structure
Query execution
Fetching result
Finding All Nodes
Repository structure:
Query execution
Fetching result
Finding Nodes by Primary Type
Repository structure:
Query execution
Fetching result
Finding Nodes by Mixin Type
Repository structure:
Query execution
Fetching result
Property Comparison
Repository structure:
Query execution
Fetching result
LIKE Constraint
Repository structure:
Query execution
Fetching result
Escaping in LIKE Statements
Repository structure
Query execution
Fetching result
NOT Constraint
Repository Structure
Query execution
Fetching the result
AND Constraint
Repository Structure:
Query execution
Fetching the Result
OR Constraint
Repository Structure
Query Execution
Fetching the Result
Property Existence Constraint
Repository Structure
Query Execution
Fetching the Result
Finding Nodes in a Case-Insensitive Way
Repository Structure
Query Execution
Fetching the Result
Date Property Comparison
Repository Structure
Query Execution
Fetching the result
Node Name Constraint
Repository Structure
Query execution
Fetching the Result
Multivalue Property Comparison
Repository Structure
Query Execution
Fetching the Result
Exact Path Constraint
Repository Structure
Query Execution
Fetching the Result
Child Node Constraint
Repository Structure
Query Execution
Fetching the Result
Finding All Descendant Nodes
Repository Structure
Query Execution
Fetching the Result
Sorting Nodes by Property
Repository Structure
Query Execution
Fetching the Result
Ordering by Descendant Nodes Property (XPath only)
Repository structure:
Query Execution
Fetching the Result
Ordering by Score
Info
Repository Structure
Query Execution
Fetching the Result
Ordering by Path or Name
Fulltext Search by Property
Repository Structure
Query Execution
Fetching the Result
Fulltext Search by All Properties in Node
Repository structure:
Query execution
Fetching result
Ignoring Accent Symbols. New Analyzer Setting.
Repository structure:
Query execution
Fetching result
Finding nt:file node by content of child jcr:content node
Repository structure:
Query execution
Fetching the result
Changing Priority of Node
Indexing configuration
Repository structure:
Query execution
Fetching result
Removing Nodes Property From Indexing Scope
Repository structure:
Query execution
Fetching result
Regular Expression as Property Name in Indexing Rules
Repository structure:
Query execution
Fetching result
High-lighting Result of Fulltext Search
Base info
Repository structure:
Query execution
Fetching result
Searching By Synonim
Repository structure:
Query execution
Fetching result
Checking the spelling of Phrase
Repository structure:
Query execution
Fetching result
Finding Similar Nodes
Repository structure:
Query execution
Fetching result
Tips and tricks
XPath queries containing node names starting with a number
29. Searching Repository Content
Introduction
Bi-directional RangeIterator (since 1.9)
Fuzzy Searches (since 1.0)
SynonymSearch (since 1.9)
High-lighting (Since 1.9)
DefaultXMLExcerpt
DefaultHTMLExcerpt
How to use it
SpellChecker
How do I use it?
Similarity (Since 1.12)
30. Fulltext Search And Affecting Settings
Property content indexing
Lucene Analyzers
How are different properties indexed?
Fulltext search query examples
Different analyzers in action
31. JCR API Extensions
"Lazy" child nodes iteration
Concept
API and usage
Configuration
Implementation notices
32. WebDAV
Related documents
Introduction
Configuration
Screenshots
MS Internet Explorer
Dav Explorer
Xythos Drive
Microsoft Office 2003
Ubuntu Linux
Comparison table of WebDav and JCR commands
Restrictions
Windows 7
Microsoft Office 2010
33. FTP
Introdution
Configuration Parameters
command-port:
data-min-port & data-max-port
system
client-side-encoding
def-folder-node-type
def-file-node-type
def-file-mime-type
cache-folder-name
upload-speed-limit
download-speed-limit
timeout
34. eXo JCR Backup Service
Concept
How it works
Implementation details
Work basics
Configuration
RDBMS backup
Usage
Performing a Backup
Performing a Restore
Restoring into an existing workspace
System workspace
Repository and Workspace initialization from backup
Restore the Workspace over BackupWorksaceInitializer
Restore the Repository over BackupWorksaceInitializer
Scheduling (experimental)
Restore existing workspace or repository
Restore a workspace or a repository using original configuration
Backup set portability
35. HTTPBackupAgent and backup client
Introduction
HTTPBackupAgent
HTTPBackupAgent methods
Starting Backup Service
Stopping Backup Service
Backup Info Service
Dropping Workspace Service
Backup Info
Current Backups Information
Completed Backups Information
Workspace-specific Backup Information
Single Backup Information
Restores on a Workspace Information
Restores Information
Restoring Service
Default Workspace Information
HTTPBackupAgent Configuration
Backup Client
Backup Client Usage
Building application
Running application
Getting information about backup service
Starting full backup
Starting full and incremental backup on a single workspace
Getting information about the current backups (in progress)
Getting information about the current backup by 'backup_id'
Stopping backup by "backup_id"
Getting information about the completed (ready to restore) backups
Restoring to workspace
Getting information about the current restore
Restoring workspace and remove exists workspace
Restoring workspace from backup set
Restoring workspace from backup set and remove exists workspace
Restoring workspace with original configuation
Restoring workspace with original configuation and remove exists workspace
Restoring workspace from backup set with original configuation
Restoring workspace from backup set with original configuation and remove exists workspace
Restoring repository
Restoring repository and remove exists repository
Restoring repository from backup set
Restoring repository from backup set and remove exists repository
Restoring repository with original configuation
Restoring repository with original configuation and remove exists repository
Restoring repository from backup set with original configuation
Restoring repository from backup set with original configuation and remove exists repository
Full example about creating backup and restoring it for workspace 'backup'
Creating backup
Getting information about current backups
Stopping backup by id
Deleting the workspace "backup" and close opened sessions on this workspace
Restoring the workspace "backup"
Getting information about restore for workspace /repository/backup
Full example about creating backup and restoring it for repository 'repository'
Creating backup
Getting information about current backups
Stopping backup by id
Deleting the repository "repository" and close all opened sessions
Restoring the repository "repository"
Getting information about restore for repository 'repository'
36. Use external backup tool
Repository suspending
Backup
Repository resuming
37. eXo JCR statistics
Statistics on the Database Access Layer
Statistics on the JCR API accesses
Statistics Manager
38. JTA
39. The JCA Resource Adapter
Overview
The SessionFactory
Configuration
Deployment
40. Access Control
Standard Action Permissions
eXo Access Control
Principal and Identity
ACL
Privilegeable
Ownable
ACL Inheritance
Default ACL of the root node
Notes
Example
XML Example
Inheritance Examples
Permission validation
Java API
41. Access Control Extension
Prerequisites
Overview
Access Context Action
The Invocation Context
Custom Extended Access Manager
Example of a custom Access Manager
42. Link Producer Service
43. Binary Values Processing
Configuration
Usage
Value implementations
44. JCR Resources:
45. JCR Workspace Data Container (architecture contract)
Goals
Concepts
Container and connection
Value storages
Lifecycle
Value storage lifecycle
Requirements
Read operations
Write operations
State operations
Validation of write operations
Consistency of save
Value storages API
Storages provider:
Value storage plugin
Value I/O channel
Transaction support via channel
46. How-to implement Workspace Data Container
Short intro about Workspace data container implementation practices:
Notes on Value storage usage:
47. DBCleanService
API
48. JCR Performance Tuning Guide
Introduction
JCR Performance and Scalability
Cluster configuration
JCR Clustered Performance
Performance Tuning Guide
JBoss AS Tuning
JCR Cache Tuning
Clustering
JVM parameters
II. eXoKernel
49. eXo Kernel
eXo Kernel introduction
50. ExoContainer info
Container hierarchy
51. Service Configuration for Beginners
Objective
Requirements
Services
Configuration File
Execution Modes
Containers
Configuration Retrieval
RootContainer
PortalContainer
StandaloneContainer
Service instantiation
Miscellaneous
Startable interface
Inversion of Control
More Containers
Single Implementation Services
Configuration properties
Configuration Logging
Further Reading
52. Service Configuration in Detail
Objectives
Requirements
Sample Service
Java Class
First configuration file
Init Parameters
Service Access
Parameters
Value-Param
Properties-Param
Object-Param
Collection
External Plugin
Import
System properties
53. Container Configuration
Intro
Kernel configuration namespace
Understanding how configuration files are loaded
Configuration Retrieval
Configuration retrieval order for the PortalContainer
Configuration retrieval for a StandaloneContainer
General notes about the configuration retrieval
Configuration retrieval log
Getting the effective configuration at Runtime
Advanced concepts for the PortalContainers
Add new configuration files from a WAR file
Creating your PortalContainers from a WAR file
Defining a PortalContainer with its dependencies and its settings
PortalContainer settings
Adding dynamically settings and/or dependencies to a PortalContainer
The existing implementations of PortalContainerDefinitionChange
AddDependencies
AddDependenciesBefore
AddDependenciesAfter
AddSettings
Disable dynamically a portal container
System property configuration
Properties init param
Properties URL init param
System Property configuration of the properties URL
Variable Syntaxes
Runtime configuration profiles
Profiles activation
Profiles configuration
Profiles definition
Profiles capable configuration elements
Component element
Component plugin element
Import element
Init param element
Value collection element
Field configuration element
Component request life cycle
Component request life cycle contract
Request life cycle
Scheduling a component request life cycle
Scheduling a container request life cycle
When request life cycle is triggered
Portal request life cycle
JMX request Life Cycle
54. Inversion Of Control
Overview
How
Injection
Side effects
55. Services Wiring
Overview
Portal Instance
Introduction to the XML schema of the configuration.xml file
Configuration retrieval and log of this retrieval
56. Component Plugin Priority
57. Understanding the ListenerService
Objectives
What is the ListenerService ?
How does it work?
Registering a listener
Triggering an event
How to configure a listener?
Concrete Example
58. Initial Context Binder
API
59. Job Scheduler Service
What is Job Scheduler?
Where is Job Scheduler Service used in eXo Products?
How does Job Scheduler work?
How can Job Scheduler Service be used in Kernel?
Samples
Define a job
Job configuration
Run the project
Reference
60. eXo Cache
Basic concepts
Advanced concepts
Invalidation
FutureExoCache
eXo Cache extension
eXo Cache based on JBoss Cache
Configuring the ExoCacheFactory
Adding specific configuration for a cache
Adding a cache creator
Understanding a cache creator
Registering a cache creator
The cache creators available
LRU Cache Creator - Least Recently Used
FIFO Cache Creator - First In, First Out
MRU Cache Creator - Most Recently Used
LFU Cache Creator - Least Frequently Used
EA Cache Creator - Expiration Algorithm
Defining a cache
How to define a cache?
At CacheService initialization
With an "external plugin"
How to define a distributed or a local cache?
How to share a JBoss Cache instance between multiple eXo Cache instances
LRU Cache - Least Recently Used
FIFO Cache - First In, First Out
MRU Cache - Most Recently Used
LFU Cache - Least Frequently Used
EA Cache - Expiration Algorithm
eXo Cache based on Infinispan
Configure the ExoCacheFactory
Add specific configuration for a cache
Add a cache creator
Understanding a cache creator
Register a cache creator
The cache creators available
Generic Cache Creator
Define an infinispan cache instance
How to define a distributed or a local cache?
How to define an infinispan cache instance
61. TransactionService
Base information
Existing TransactionService implementations
JOTM in standalone mode
Generic TransactionService based on the TransactionManagerLookup of JBoss Cache
Specific GenericTransactionService for JBoss Cache and Arjuna
Generic TransactionService based on the TransactionManagerLookup of Infinispan
Specific GenericTransactionService for Infinispan and Arjuna
A very specific TransactionService for JBoss AS
TransactionsEssentials in standalone mode
62. The data source provider
Description
Configuration
63. JNDI naming
Prerequisites
How it works
JNDI System property initialization
JNDI reference binding
Configuration examples
Recommendations for Application Developers
InitialContextInitializer API
64. Logs configuration
Introdution
Logs configuration initializer
Configuration examples
Log4J
Assigning logger level for classes or components
JDK Logging
Commons Logging SimpleLogss
Tips and Troubleshooting
JBoss tips
Other tips
65. Manageability
Introduction
Managed framework API
Annotations
@org.exoplatform.management.annotations.Managed annotation
@org.exoplatform.management.annotations.ManagedDescription
@org.exoplatform.management.annotations.ManagedName
@org.exoplatform.management.annotations.ManagedBy
JMX Management View
JMX Annotations
@org.exoplatform.management.jmx.annotations.Property annotation
@org.exoplatform.management.jmx.annotations.NameTemplate annotation
@org.exoplatform.management.jmx.annotations.NamingContext annotation
Example
CacheService example
66. ListenerService
Asynchronous Event Broadcast
67. RPC Service
Description
Configuration
The SingleMethodCallCommand
III. eXoCore
68. eXo Core
eXo Core introduction
69. Database Creator
About
API
A configuration examples
An examples of a DDL script
70. Security Service
1 Overview
1 Framework
1.1 ConversationState and ConversationRegistry
1.1 Authenticator
Usage
JAAS login module
1.1 Predefinded JAAS login modules
1.1 J2EE container authentication
71. Spring Security Integration
Introduction
Installation
Configuration
JAAS disabling
Enabling spring security
security-context.xml
Login portlet example
Building the portlet
Setting up the login portal page
Customization of portal login and logout urls
A look at the login page
Integration strategies
Replication
Integration with eXo portal
Security context propagation to portlets
Portal side filter
Portlet side filter
Conclusion
72. Organization Service
Overview
Organizational Model
User
Group
Membership
Related articles and how-tos
73. Organization Service Initializer
74. Organization Listener
Overview
Writing your own listeners
UserEventListener
GroupEventListener
MembershipEventListener
Registering your listeners
75. Update ConversationState when user's Membership changed
76. DB Schema creator service (JDBC implementation)
77. Database Configuration for Hibernate
Generic configuration
Example DB configuration
Registering custom Hibernate XML files into the service
78. LDAP Configuration
Overview
Quickstart
Configuration
Connection Settings
Organization Service Configuration
Users
Main parameters
User mapping
Groups
Membership Types
Memberships
User Profiles
Advanced topics
Automatic directory population
Active Directory sample configuration
OpenLDAP dynlist overlays
79. Tika Document Reader Service
Intro
Architecture
Configuration
Old-style DocumentReaders and Tika Parsers
How to make and register own DocumentReader
TikaDocumentReader features and notes
80. Digest Authentication
Overview
Server configuration
Tomcat Server configuration
Jetty server configuration
JBoss server configuration
OrganizationService implementation requirements
IV. eXoWS
81. eXo Web Services
eXo Web Services introduction
82. Introduction to the Representational State Transfer (REST)
Introduction
83. OverwriteDefaultProviders
Motivation
Usage
Example
84. RestServicesList Service
Overview.
Usage
HTML format
JSON format
85. Groovy Scripts as REST Services
Overview
Loading script and save it in JCR
Instantiation
Deploying newly created Class as RESTful service
Script Lifecycle Management
Getting node UUID example
Groovy script restrictions
86. Framework for cross-domain AJAX
Motivation
Scheme (how it works)
A Working Sequence:
How to use it
V. Frequently Asked Question
87. JCR FAQ
Kernel
What is the best, standardized way to get the instance of a service ?
JCR
JCR core
Is it better to use Session.getNodeByUUID or Session.getItem?
Does it make sense to have all the node referencable to use getNodeByUUID all the time?
What should I use to check if an Item exists before getting the Value?
How to use Observation properly?
Is it better to use queries that to access the data by the JCR API?
What is default query ordering?
Is ordering by jcr:path or Item name supported?
How eXo JCR indexer uses content encoding?
Which database server is better for eXo JCR?
How to setup eXo JCR for mutilingial content on MySQL?
Does MySQL have limitation affecting on eXo JCR features?
Does use of Sybase database need special options in eXo JCR configuration?
How to open and close a session properly to avoid memory leaks?
Can I use Session after loging out?
How to configure jcr for cluster ?
How to use lucene spellchecker?
How can I affect to spellchecker results?
JCR extensions
How to restore repository to existing repository ?
How to restore workspace to existing worksapce?
Does JCR support hot backup?
WebDAV
I uploaded a file to WebDAV server using Mac OS Finder, but the file size is '0', what is wrong ?
Can I manage 'cache-control' value for different media-types from server configuration ?
How to perform WebDAV requests using curl ?
How eXo JCR WebDAV server treats content encoding?
VI. eXo JCR with GateIn
88. How to extend my GateIn instance?
Introduction
Overview
Motivations
Prerequisites
Removing all the hard coded portal container name (i.e. "portal")
Removing all the hard coded rest context name (i.e. "rest")
Removing all the hard coded realm name (i.e. "exo-domain")
Making your Http Filters compatible
Making your HttpServlets compatible
Making your HttpSessionListeners compatible
Use init tasks if you need a PortalContainer to initialize an Http Filter or an HttpServlet
Making your LoginModules compatible
Avoiding static modifier on component dependency
Avoid component initialization based on component dependency in the constructor
FAQ
What has changed since the previous versions?
What is the main purpose of a portal extension?
What is the main purpose of the starter?
How a portal and a portal container are related?
How to define and register a PortalContainerDefinition?
How the platform interprets the dependency order defined into the PortalContainerDefinition?
How to change the ServletContext name, the realm name and/or the rest context name of my portal without using a PortalContainerDefinition?
On JBoss (tested on JBoss 5.1.0.GA)
On Tomcat (tested on Tomcat 6.0.20)
How to add new configuration file to a given portal from a war file?
How to create/define a portal extension?
How to deploy a portal extension?
How to create/define a new portal?
How to deploy a new portal?
How to import properly a configuration file using the prefix "war:"?
How to avoid duplicating configuration files just to rename a simple value?
How to add or change a Repository and/or a Workspace?
How to add new ResourceBundles to my portal?
How to overwrite existing ResourceBundles in my portal?
How to replace a groovy template of my portal?
How to add new Portal Configurations, Navigations, Pages or Portlet Preferences to my portal?
How to add new Http Filters to my portal without modifying the portal binary?
How to add new HttpSessionListeners and/or ServletContextListeners to my portal without modifying the portal binary?
How to add new HttpServlet to my portal without modifying the portal binary?
How to override or add a Context Parameter to my portal without modifying the portal binary?
Where can I found an example of how to extend my portal?
How to deploy the sample extension?
On JBoss (tested on JBoss 5.1.0.GA)
On Tomcat (tested on Tomcat 6.0.20)
Where can I find an example of how to create a new portal?
How to deploy the sample portal?
On JBoss (tested on JBoss 5.1.0.GA)
On Tomcat (tested on Tomcat 6.0.20)
I get "java.lang.IllegalStateException: No pre init tasks can be added to the portal container 'portal', because it has already been initialized." what can I do to fix it?
Recommendations
Don't ship your configuration files with your jar files?
Using a dedicated workspace/repository for your extension?
89. How to use AS Managed DataSource under JBoss AS
Configurations Steps
Declaring the datasources in the AS
Do not let eXo bind datasources explicitly