学习笔记

Frequently Asked Questions

General

1. What is JCR?什么是JCR？
2. What is a content repository?什么是内容库？
3. What is Jackrabbit? 什么是Jackrabbit？
   

Building Jackrabbit

1. How do I build the Jackrabbit sources?如何编译Jackrabiit源代码？
2. Why does the Maven build fail with the message "You must define currentVersion in your POM."?
   为什么使用Maven编译会出现“ You must define currentVersion in your POM.”的错误？
3. Why does the Maven build fail with the message "java.net.ConnectException: Connection timed out: connect"?
   为什么使用Maven编译会出现 "java.net.ConnectException: Connection timed out: connect" 的错误？

Using Jackrabbit

1. How do I do X with JCR/Jackrabbit?如何入门？
2. How do I use transactions with JCR?如何在JCR中使用事务处理？
3. How do I create new workspaces in Jackrabbit?如何在Jackrabbit中新建工程空间？
4. How do I delete a workspace in Jackrabbit?如何在Jackrabbit中删除工程空间？

Access control

1. How do I use LDAP, Kerberos, or some other authentication mechanism with Jackrabbit?
   如何将LDAP，kerberos集成到Jackrabbit中使用？
   
2. How do I manage the access rights of authenticated users?
   如何管理用户的访问权限？
   

Persistence managers

1. What is a persistence manager?什么是持久化管理器？
2. What is a Jackrabbit file system?什么是Jackrabbit文件系统？
3. Can I use a persistence manager to access an existing data source?
   是否能使用持久化管理器访问已有的数据源？
4. How "smart" should a persistence manager be?持久化管理器的灵活性如何？
5. What persistence managers are available?有那些持久化管理器可以使用？
6. What Jackrabbit file systems are available?有那些文件系统科研使用？
7. Which persistence manager and file systems should I use?如何选择持久化管理器和文件系统？

General

What is JCR?

JCR is the acronym of the JSR 170: Content Repository for Java? technology API, a standard interface for accessing content repositories.
JCR是JSR170的缩写，是访问内容库的标准接口。

What is a content repository?

A content repository is an information management system that provides various services for storing, accessing, and managing content. In addition to a hierarchically structured storage system, common services of a content repository are versioning, access control, full text searching, and event monitoring.
内容库是一个信息管理系统，用于提供存储、访问和管理内容。此外还提供hierarchically structured的存储系统，内容库的版本控制、访问控制权限、全文检索和事件监控。

A content repository is not a content management system (CMS), although most of the existing CMSs contain a more or less featured custom content repository implementation. A CMS uses a content repository as an underlying component for presentation, business logic, and other features.
内容库不是CMS，虽然很多现有的CMS包括或多或少和内容库类似的功能实现。CMS是将内容库用于底层组件，以用来表现、商业逻辑和其他功能。

What is Jackrabbit?

The Apache Jackrabbit is a fully featured content repository that implements all of the JCR API. The Jackrabbit project was started when Day Software, the JSR-170 specification lead, licensed their initial implementation of the JCR reference implementation. Since then the Jackrabbit codebase has been used for the official reference implementation (RI) and technology compatibility kit (TCK) released along with the final JCR API.
Apache Jackrabbit完整实现JCR API的内容库。Jackrabbit起步于Day Software，DaySoftware是JSR170的领导者，Jackrabbit是基于DaySoftware对JCR的最初实现项目。Jackrabbit在JCRAPI最终发布时，是作为官方的参考实现和相容性开发包。

Building Jackrabbit

How do I build the Jackrabbit sources?

See the Building Jackrabbit section of the Jackrabbit documentation for detailed build instructions.
查看Jackrabbit文档中Building Jackrabbit段落中的具体操作指南。

Why does the Maven build fail with the message "You must define currentVersion in your POM."?

You are most probably running Maven from a wrong directory. Maven expects to find the file project.xml in the current directory (unless the -d, -p, or -f option is given). Please check that you are in the correct directory and try running Maven again.
您很有可能在一个错误的目录运行了Maven。Maven需要当前目录找到project.xml（除非-d,-p,或者-f的参数被指）。所以请检查你是否在正确的目录，并再次尝试运行Maven。

Why does the Maven build fail with the message "java.net.ConnectException: Connection timed out: connect"?

This error message can appears when one of the Maven repositories used for downloading Jackrabbit dependencies is not available. This can happen if your network connection is broken or if the repository server is down. Please check your network connection or wait a while for the repository to come back online.
此错误是在Maven不能下载Jackrabbit的依赖库出现的，很有可能是你的网络连接没有建立或者Maven的资源服务器当机了。请检查您的网络连接情况或者等待Maven的资源服务器启动运行。

Using Jackrabbit

How do I do X with JCR/Jackrabbit?

See the JCR specification, the JCR API documentation, or the Examples page on the Jackrabbit wiki for information on how to perform various operation using the JCR API.
查看JCR标准，JCRAPI文档或者在Jackrabbit wiki上的示例。示例提供了如何使用JCR API的各种操作。

For Jackrabbit features (like access control and node type management) not covered by the JCR API, see the Examples page on the wiki, the Jackrabbit javadocs, or contact the Jackrabbit mailing list.
有些Jackrabbit功能（比如访问控制，节点类型管理）不存在JCRAPI中。所以查看wiki上的示例，Jackrabbit的javadocs，或者联系Jackrabbit的邮件列表。

How do I use transactions with JCR?

See the mailing list announcement for a simple example on using the JTA support in Jackrabbit.
查看Jackrabbit的邮件列表中使用JTA的文档。

For a more complete explanation of the transaction features, please see section 8.1 Transactions of the JCR specification.
如果需要，可以查看JCR表中中8.1节中对事务功能的详细完整说明。

How do I create new workspaces in Jackrabbit?

The JCR API does not contain features for creating or managing workspaces, so you need to use Jackrabbit-specific functionality for creating new workspaces.
JCR API不包含创建和管理工程空间的功能，所以你需要使用Jackrabbit特定的新建工程空间的功能。

You can create a new workspace either manually or programmatically. The manual way is to create a new workspace directory within the repository home directory and to place a new workspace.xml configuration file in that folder. You can use the configuration file of an existing workspace as an example, just remember to change the name of the workspace in the <Workspace name="...">" tag. See the Configuring Jackrabbit page for configuration details. Note also that you need to restart the repository instance to access the new workspace.
你可以手工新建一个工程空间，也可以书写程序代码来新建一个工程空间。手工方式的实现：在内容库的主目录下新建一个工程空间目录，并将一个workspace.xml配置文件放在此工程目录下。你可以借用一个已经存在的工程空间的配置文件，仅需要记得修改其中的工程空间名称（在<Workspace name="...">" 标签中修改）。你可以在配置Jackrabbit页面得知更多的配置信息内容。最后提醒你：重启内容库，才能访问到新建的工程空间。

The programmatic way is to acquire a Workspace instance using the normal JCR API and to cast the instance to the Jackrabbit WorkspaceImpl class. You can then use the WorkspaceImpl.createWorkspace(String) method to create new workspaces.
程序代码方式的实现：你首先需要通过JCR API获取Workspace实例，然后将其转型成为Jackrabbit的WorkspaceImpl实例。之后你可以使WorkspaceImpl.createWorkspace(String)的方法新建一个工程空间。

How do I delete a workspace in Jackrabbit?

There is currently no programmatic way to delete workspaces. You can delete a workspace by manually removing the workspace directory when the repository instance is not running.
现在没有程序方式进行删除工程空间的方法。你可以在内容库没有运行的情况下手工删除工程空间目录。

Access control

How do I use LDAP, Kerberos, or some other authentication mechanism with Jackrabbit?

Jackrabbit uses the Java Authentication and Authorization Service (JAAS) for authenticating users. You should be able to use any JAAS LoginModule implementation (e.g. the LoginModules in the com.sum.security.auth.module package) for authentication. See the JAAS documentation for configuration instructions.
Jackrabbit使用JAAS对用户进行鉴别。你可以继承实现JAAS LoginModule类（比如sun提供的LoginModules）用于用户的鉴别。具体请看JAAS的文档进行配置。

How do I manage the access rights of authenticated users?

The current Jackrabbit SimpleAccessManager class only supports three access levels: anonymous, normal, and system. Anonymous users have read access while normal and system users have full read-write access. You need to implement a custom AccessManager class to get more fine-grained access control.当前版本的中SimpleAccessManager类只支持三个访问级别：匿名，普通和系统。匿名用户拥有读的权限，普通和系统用户拥有全部的读写权限。你需要继承实现AccessManager类进行扩展，获取更多的访问权限控制。

Persistence managers

What is a persistence manager?

A persistence manager (PM) is an internal Jackrabbit component that handles the persistent storage of content nodes and properties. Each workspace of a Jackrabbit content repository uses a separate persistence manager to store the content in that workspace. Also the Jackrabbit version handler uses a separate persistence manager.

The persistence manager sits at the very bottom layer of the Jackrabbit system architecture. Reliability, integrity and performance of the PM are crucial to the overall stability and performance of the repository. If e.g. the data that a PM is based upon is allowed to change through external means the integrity of the repository would be at risk (think of referential integrity / node references e.g.).

In practice, a persistence manager is any Java class that implements the PersistenceManager interface and the associated behavioural contracts. Jackrabbit contains a set of built-in persistence manager classes that cover most of the deployment needs. There are also a few contributed persistence managers that give additional flexibility.

What is a Jackrabbit file system?

A Jackrabbbit file system (FS) is an internal component that implements standard file system operations on top of some underlying storage mechanism (a normal file system, a database, a webdav server, or a custom file format). A file system component is any Java class that implements the FileSystem interface and the associated behavioural contracts. File systems are used in Jackrabbit both as subcomponents of the persistence managers and for general storage needs (for example to store the full text indexes).

Can I use a persistence manager to access an existing data source?

No. The persistence manager interface was never intended as being a general SPI that you could implement in order to integrate external data sources with proprietary formats (e.g. a customers database). The reason why we abstracted the PM interface was to leave room for future performance optimizations that would not affect the rest of the implementation (e.g. by storing the raw data in a b-tree based database instead of individual file).

How "smart" should a persistence manager be?

A persistence manager should not be intelligent, i.e. it should not interpret the content it is managing. The only thing it should care about is to efficiently, consistently, and reliably store and read the content encapsulated in the passed NodeState and PropertyState objects. Though it might be feasible to write a custom persistence manager to represent existing legacy data in a level-1 (read-only) repository, I don’t think the same is possible for a level-2 repository and I certainly would not recommend it.

What persistence managers are available?

The table below lists the currently available persistence managers, along with the status and pros and cons of each PM.

Persistence manager	Status	Pros	Cons
SimpleDbPersistenceManager (and subclasses thereof)	mature	Jackrabbit’s default persistence manager JDBC based persistence supporting a wide range of RDBMSs zero-deployment, schema is automatically created Transactional	uses simple non-normalized schema and binary serialization format which might not appeal to relational data modeling fans
BerkeleyDBPersistenceManager	mature?	btree-based persistence (BerkeleyDB JE) zero-deployment Transactional	Uses binary serialization format Licensing issues
ObjectPersistenceManager	mature	File system based persistence Easy to configure	Uses binary serialization format If the JVM process is killed the repository might turn inconsistent Not transactional
XMLPersistenceManager	mature	File system based persistence Uses XML serialization format Easy to configure	If the JVM process is killed the repository might turn inconsistent Poor performance Not transactional
ORM persistence manager	experimental & unfinished	ORM-based persistence Transactional	Complex to configure & setup Still being maintained?

What Jackrabbit file systems are available?

The table below lists the currently available Jackrabbit file systems, along with the status and pros and cons of each FS.

File system	Status	Pros	Cons
LocalFileSystem	mature		Slow on Windows boxes
DbFileSystem	mature	JDBC based file system supporting a wide range of RDBMSs zero-deployment, schema is automatically created	Slower than native file systems
CQFS file system	mature	Fast on Windows boxes	Undocumented configuration options Proprietary binary format Not open source

Which persistence manager and file systems should I use?

The answer depends on your priorities. If you want to store your data in a RDBMS, use SimpleDbPersistenceManager and either LocalFileSystem or DbFileSystem. If you want to store your data in an accessible format (just in case or for manual debugging), you might want to try the XMLPersistenceManager and the LocalFileSystem. If you use Windows and performance is a must, you might want to try the ObjectPersistenceManager and the proprietary CQFS.