學(xué)習(xí)筆記

Frequently Asked Questions

General

1. What is JCR?什么是JCR？
2. What is a content repository?什么是內(nèi)容庫？
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編譯會出現(xiàn)“ 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編譯會出現(xiàn) 的錯誤？

Using Jackrabbit

1. How do I do X with JCR/Jackrabbit?如何入門？
2. How do I use transactions with JCR?如何在JCR中使用事務(wù)處理？
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?
   如何管理用戶的訪問權(quán)限？
   

Persistence managers

1. What is a persistence manager?什么是持久化管理器？
2. What is a Jackrabbit file system?什么是Jackrabbit文件系統(tǒng)？
3. Can I use a persistence manager to access an existing data source?
   是否能使用持久化管理器訪問已有的數(shù)據(jù)源？
5. What persistence managers are available?有那些持久化管理器可以使用？
6. What Jackrabbit file systems are available?有那些文件系統(tǒng)科研使用？
7. Which persistence manager and file systems should I use?如何選擇持久化管理器和文件系統(tǒng)？

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的縮寫，是訪問內(nèi)容庫的標(biāo)準(zhǔn)接口。

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.
內(nèi)容庫是一個信息管理系統(tǒng)，用于提供存儲、訪問和管理內(nèi)容。此外還提供hierarchically structured的存儲系統(tǒng)，內(nèi)容庫的版本控制、訪問控制權(quán)限、全文檢索和事件監(jiān)控。

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.
內(nèi)容庫不是CMS，雖然很多現(xiàn)有的CMS包括或多或少和內(nèi)容庫類似的功能實(shí)現(xiàn)。CMS是將內(nèi)容庫用于底層組件，以用來表現(xiàn)、商業(yè)邏輯和其他功能。

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完整實(shí)現(xiàn)JCR API的內(nèi)容庫。Jackrabbit起步于Day Software，DaySoftware是JSR170的領(lǐng)導(dǎo)者，Jackrabbit是基于DaySoftware對JCR的最初實(shí)現(xiàn)項(xiàng)目。Jackrabbit在JCRAPI最終發(fā)布時(shí)，是作為官方的參考實(shí)現(xiàn)和相容性開發(fā)包。

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.
您很有可能在一個錯誤的目錄運(yùn)行了Maven。Maven需要當(dāng)前目錄找到project.xml（除非-d,-p,或者-f的參數(shù)被指）。所以請檢查你是否在正確的目錄，并再次嘗試運(yùn)行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的依賴庫出現(xiàn)的，很有可能是你的網(wǎng)絡(luò)連接沒有建立或者M(jìn)aven的資源服務(wù)器當(dāng)機(jī)了。請檢查您的網(wǎng)絡(luò)連接情況或者等待Maven的資源服務(wù)器啟動運(yùn)行。

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標(biāo)準(zhǔn)，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功能（比如訪問控制，節(jié)點(diǎn)類型管理）不存在JCRAPI中。所以查看wiki上的示例，Jackrabbit的javadocs，或者聯(lián)系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節(jié)中對事務(wù)功能的詳細(xì)完整說明。

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不包含創(chuàng)建和管理工程空間的功能，所以你需要使用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.
你可以手工新建一個工程空間，也可以書寫程序代碼來新建一個工程空間。手工方式的實(shí)現(xiàn)：在內(nèi)容庫的主目錄下新建一個工程空間目錄，并將一個workspace.xml配置文件放在此工程目錄下。你可以借用一個已經(jīng)存在的工程空間的配置文件，僅需要記得修改其中的工程空間名稱（在<Workspace name="...">" 標(biāo)簽中修改）。你可以在配置Jackrabbit頁面得知更多的配置信息內(nèi)容。最后提醒你：重啟內(nèi)容庫，才能訪問到新建的工程空間。

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.
程序代碼方式的實(shí)現(xiàn)：你首先需要通過JCR API獲取Workspace實(shí)例，然后將其轉(zhuǎn)型成為Jackrabbit的WorkspaceImpl實(shí)例。之后你可以使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.
現(xiàn)在沒有程序方式進(jìn)行刪除工程空間的方法。你可以在內(nèi)容庫沒有運(yùn)行的情況下手工刪除工程空間目錄。

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對用戶進(jìn)行鑒別。你可以繼承實(shí)現(xiàn)JAAS LoginModule類（比如sun提供的LoginModules）用于用戶的鑒別。具體請看JAAS的文檔進(jìn)行配置。

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.當(dāng)前版本的中SimpleAccessManager類只支持三個訪問級別：匿名，普通和系統(tǒng)。匿名用戶擁有讀的權(quán)限，普通和系統(tǒng)用戶擁有全部的讀寫權(quán)限。你需要繼承實(shí)現(xiàn)AccessManager類進(jìn)行擴(kuò)展，獲取更多的訪問權(quán)限控制。

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.