Exploring CRX

You are reading the CRX 2.3 version of Exploring CRX.
This version has reached End of core support. For further details see our technical support periods.
This documentation is also available for the following versions:  CRX 2.2  CRX 2.1 

CRX is a data storage system specifically designed for content-centric applications. CRX implements the Content Repository API for Java Technology (JCR). This standard defines a data model and application programming interface (that is, a set of commands) for content repositories. A JCR repository can be thought of as a "super file system". It combines characteristics of conventional file systems with those of relational databases, and adds a number of additional features that content applications often need.

What is JCR?

A content repository, as defined by JCR, combines features of the traditional relational database with those of a conventional file system.

File system-like features supported by JCR include:

  • Hierarchy: Content in a JCR repository can be addressed by path. This is useful when delivering content to the web since most websites are also organized hierarchically.
  • Semi-structured content: JCR can store structured documents, like XML, either as opaque files (as a file system would) or as structures ingested directly into the JCR hierarchy.
  • Access Control and Locking: JCR can restrict access to different parts of the content hierarchy based on policies or ACLs. It also supports locking of content to prevent conflicts.

Database-like features supported by JCR include:

  • Query Access: JCR supports querying with languages such as SQL.
  • Structured Content: JCR can enforce constraints on data structures according to schema.
  • Referential Integrity: JCR can enforce referential integrity between content items.
  • Transactions: Interactions with a JCR repository can be bracketed in transactions and rolled back when needed.

In addition, JCR provides the following services that content-centric applicaitons often need, but that neither file systems nor databases typically provide:

  • Unstructured Content: JCR can also support arbitrary dynamic data structures without schema constraints.
  • Full-text search: JCR supports full-text search of content.
  • Sort order: Items within the hierarchy can maintain their ordering, if desired.
  • Observation: API clients can register listeners to react to changes made to the repository.
  • Versioning: JCR supports an advanced versioning system for repository content.

For more information, see the JCR specification (in HTML).

JCR Repository Model

Inside a JCR repository, content is organized into one or more workspaces, each of which holds of a hierarchical structure of nodes and properties.

Beginning with the root node at the top, the hierarchy descends much like the directory structure of a file system: each node can have zero or more child nodes and zero or more properties. Properties cannot have children but do have values.

The values of properties are where the actual pieces of data are stored. These can be of different types: strings, dates, numbers, binaries and so forth. The structure of nodes above the properties serves to organize this data according to whatever principles are employed by the application using the repository. Here is a schematic showing a workspace with a simple tree of nodes and properties:

file

This diagram depicts the content of a workspace W0 in repository R.

Paths and Identifiers

Every node and property in the workspace has a name and every node has an identifier. The names allow each node and property to be addressed by path, much like in a file system. For example, above, the property /A/D has as its value the string "Once upon a time..." and the node /A/E has property I which holds a binary property.

The identifier of a node has to be unique within the workspace, so that each node can also be addressed directly by its identifier. For example, above, the node /A/E has the identifier 0004.

An Example Workspace in CRX

The picture above is greatly simplified, to see a more realistic example, you can examine the repository in your local CRX installation. Assuming you have administrator access, simply go to the CRX Launchpad page and click the link CRXDE Lite (http://localhost:7402/crx/de/ in a default installation). This opens the web-based development environment for CRX.

file

In the top right you will see the username and workspace that you are logged into:

file

On the left side the node hierarchy of the workspace is displayed. The node highlighted in the picture below is /apps/firststeps/0_hello.html:

file

On the bottom of the screen the properties of the node /apps/firststeps/0_hello.html are shown:

file

Property Types

Notice in the picture above that each of the three properties has a type. In the above example there are three properties jcr:created, jcr:createdBy and jcr:primaryType of types DATE, STRING and NAME, respectively. In fact, there are twelve possible property types in JCR:

  • STRING: A piece of text.
  • URI: A universal resource identifier.
  • BOOLEAN: A boolean value (true or false).
  • DATE: A calender date and/or time.
  • LONG: An integer number.
  • DOUBLE: A floating point number.
  • DECIMAL: An arbitrary-precision signed decimal number.
  • PATH: A path to a node or property.
  • NAME: The name of a node, property or other JCR entity.
  • BINARY: Raw binary data.
  • REFERENCE: A reference to another node in the workspace by identifier, that does not permit the removal of the target (it enforces referential integrity).
  • WEAKREFERENCE: A reference to another node in the workspace by identifier, that does permit the removal of the target (it does not enforces referential integrity).

Node Types

Just as properties have types, so do nodes. Looking again at the list of properties of the node
/apps/firststeps/0_hello.html, above, you will see that one of the properties is jcr:primaryType of type NAME. This property is one of a number of special properties that every node automatically has. In this case the property records the name of the node's type: nt:file.

Every node has a node type that defines what subnodes and properties it can have. Above, the type nt:file indicates that the node /apps/firststeps/0_hello.html represents a File object.

Example Node Types in CRX

To see the node types registered in your CRX instance you can point your browser to the the CRX main console:

http://<your-crx>/crx/index.jsp

For example, in the default installation on your local machine this would be:

http://localhost:7402/crx/index.jsp

(note that you will need administrator access)

The main console page will appear:

file

Click the Log In link and log in as an administrator (by default the login is admin and the password is admin). Then click on Node Type Administration. This will take you to a console that shows all the regsitered node types in your CRX instance. Scroll down until you see nt:file in the left pane and click on it. This will reveal the defintion of that node type:

file

For the time being we don't need to go into all the details of this node type definition. The main things to notice are the two subsections entitled Child Node Definitions and Property Definitions. These list the child nodes and properties that a node of type nt:file is permitted (or required) to have.

Looking first at the Property Definitions, we see that four properties are listed: jcr:created, jcr:createdBy, jcr:mixinTypes and jcr:primaryType. A few things to notice:

  • The names of the properties are grayed-out. This indicates that they have been inherited from the defintions of supertypes of nt:file. and are not defined in nt:file itself. This demonstrates an important feature: Node types support inheritance.
  • The Column called Man indicates whther a property or subnode is mandatory. In the case of the properties listed, only jcr:primaryType is mandatory. That means that every node of type nt:file must have a property jcr:primaryType (in fact, every node is required to have this property). The other properties are not mandatory, meaning that a node of type nt:file may have these properties. This demonstrates another feature: Node types can enforce structure.

In the Child Node Definitions we see one entry: jcr:content. The jcr:content entry indicates that a subnode called jcr:content is permitted and that that node must be of type nt:base. Additional allowed child node definitions could be listed here, and an entry with a * (asterisk) as name, would indicate that any other subnodes may also be added with any types. The main thing to notice here is:

  • The * entry indicates that there are no restrictions on subnodes being added to nodes of type nt:file. This demonstartes another principle of JCR: Node types don't always enforce structure, they can also permit unstructured content.

Summary of the JCR Repository Model

The main features of the JCR repository model are:

  • A repository consist of one or more workspaces.
  • Each workspace consists of a hierarchy of nodes and properties.
  • Nodes and properties can be addressed by path.
  • Nodes can also be addressed directly by unique identifiers.
  • Properties store the actual content of the repository.
  • Nodes provide the strucural organization of the content.
  • Properties have types.
  • Nodes have types
  • A node's type governs which properties and subnodes it may or must have.
  • Node types can be used to enforce constarints on content structures.
  • But, JCR also supports free-form unstructured content.

Download and Start Working

This section gets you up and running with CRX quickly.

Download CRX

CRX comes in a few product editions to match your usage and deployment needs. Please visit the CRX page on day.com to decide, which CRX edition is right for you.

To download CRX for production use, visit the Daycare website and click Download CRX.

To download the CRX Developer Edition, which is free to use for all non-production purposes, visit the CRX Developer download page.

Installing, Starting, and Stopping CRX

This section describes how to install, start, and stop CRX instances. For troubleshooting tips during installation, see Troubleshooting.

Installing CRX

To install CRX:

  1. Copy the CRX quickstart jar file (crx-<version>-<edition>.jar) to the desired directory on the host file system.

    Caution

    Only US-ASCII characters are allowed in the name of the folder used to store the Quickstart jar (or any other runnable jar).

  2. Copy a valid license.properties file into the same directory as the quickstart jar file.

    Note

    Note: If when starting the application, you do not provide the license.properties file, CRX asks you for a valid license key. You can request a valid license key from Day at this time.

  3. Start CRX Quickstart for the first time.

    • When CRX is started for the first time, it will automatically create a crx-quickstart folder in the same directory as the quickstart jar file. 
    • Inside the crx-quickstart directory, CRX will place its working files and create a fresh repository.

    Due to this initialization process, the first startup will take longer than subsequent startups. See Starting CRX for detailed instructions on how to start CRX Quickstart.

Starting CRX

In order to start CRX, simply double-click CRX Quickstart or start CRX from the command line or a custom script.

To start CRX:

  1. Navigate to the quickstart jar file (crx-<version>-<edition>.jar), either in your GUI file-system window or in a terminal, using the command line.

  2. Do one of the following:

    • If using a GUI (for example, Windows Explorer or MAC Finder), double-click the quickstart jar file (crx-<version>-<edition>.jar).
    • If using the command line, enter the java command using the following principle:
      with a 32bit VM:
          java -Xmx384M -jar crx-<version>-<edition>.jar
      or, with a 64bit VM
          java -XX:MaxPermSize=128m -Xmx512M -jar crx-<version>-<edition>.jar
      CRX is ready when the message "Press CTRL-C to shutdown the Quickstart server..." is seen.

    Note

    By default, CRX will automatically open a browser window on startup. When starting CRX from the command line on a remote server, you may want to suppress this by adding the -nobrowser option to the above command line.

  3. In order to automate the startup of CRX, you can use a startup script.

    When CRX is started the first time, it places example startup scripts in the crx-quickstart/server folder. The start and stop scripts are for UNIX, Linux and Macintosh, the server.bat script is for Windows.

Note

See Configuring JVM Settings for CRX if you need to change some of the advanced JVM settings for CRX (such as JVM memory size).

CRX starts and automatically opens the appropriate page in your web browser. Once started, you have access to CRX. See the CRX User Guide for details on using CRX.

file

Showing Startup Statistics

The CRX Quickstart window shows the startup time:

file

This also forms a link to startup statistics of the individual elements:

file

Stopping CRX

To stop CRX, do one of the following:

  • If you started CRX from the command line, press Ctrl+C to shut down the server.
  • If you started CRX with the start script, now use the stop script.
  • If you started CRX by double-clicking on the jar file, click on the On button in the Quickstart window. This will change to Off as the server shuts down.

Getting around in CRX

This guide tells you how to manage and use the CRX repository through the Web-based tools.

CRX Launchpad

CRX Launchpad is an enhanced welcome screen and repository dashboard, providing access to the most frequently used repository functions. Additionally, it enables users to work with the repository content directly from desktop via WebDAV integration and to find content easily through search screen.

To access the CRX Launchpad, type the path you specified when installing CRX, such as:

http://www.myCompany.com:4502/libs/crx/core/content/welcome.html
http://localhost:4502/libs/crx/core/content/welcome.html


        

Code samples are intended for illustration purposes only.

file
From the CRX Launchpad, you can perform a number of activities, including using your content, developing with CRX, and managing the content repository.
CRXDE Lite
Develop applications with a web-based IDE.
Packages 
Package and share applications.
Package Share Download applications from Adobe and the community.
Security Manage users and groups.
Clustering
Manage clustered deployements.
Backup
Carry out backup tasks.

Searching Repository Content

To search for content stored within the repository:

  1. In the CRX Launchpad, click CRXDE LITE. The search field will be available in the middle of the page.

  2. Type a query and click Search. CRX returns any relevant content from the repository with the search terms highlighted.

Note

If CRX does not return excerpts or highlight search terms, these features have not been enabled. See