學習筆記

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編譯會出現 的錯誤？

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?
   是否能使用持久化管理器訪問已有的數據源？
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.