Chromattic

The boostrap is the creation and the configuration of the Chromattic runtime. Usually the bootstrap occurs during the initialization of the application, for instance in a web application, it is most often performed in a ServletContextListener initialization.

Chromattic bootstrap relies mainly on the ChromatticBuilder object. The builder is configured with the Chromattic application classes to obtain an instance of the Chromattic object. The Chromattic object can be used to create ChromatticSession objects. The ChromatticSession is the main runtime API used to interract with Chromattic.

    ChromatticBuilder builder = ChromatticBuilder.create();  
    builder.add(Page.class);  
    Chromattic chromattic = builder.build();  

	Creates the builder object
	We add the Page class to the builder object
	Now the Chromattic object can be created

We have just explained how to obtain a Chromattic object thanks to the builder. Now it is time to show how to obtain and use the ChromatticSession with the goal to insert a new page node. Let's examine the code:

    ChromatticSession session = chromattic.openSession();  
    try
    {
      Page page = session.insert(Page.class, "index");  
      page.setTitle("Hello Page");  
      page.setContent("Hello World");  
      session.save();  
    }
    finally
    {
      session.close();  
    }

	Any Chromattic interaction requires to open a session
	A new page is inserted under the /index path
	Set the title property
	Set the content property
	Saves the session to persist changes in the repository
	We must close the session to properly release the session

Building with Maven is very easy and only requires a dependency on the Chromattic API and APT module in your pom file.

And that's it, we have just configured our project.

JCR provides two types to map generic data types:

The string type is pretty straightforward to use, you simplet get or set the string that is mapped to the JCR property.

The binary type can be used in two different manners, the first one maps the BINARY type to a byte array. This mapping style is similar to the string mapping except that a byte array is not immutable. The client has the opportunity to alter the array as Chromattic cannot prevent it to be modified. This mapping style is very straightforward too but has the inconvenient to load the whole stream into memory which is not always desirable for very large streams.

The other manner maps the BINARY type to an java.io.InputStream. This behavior is actually the JCR native behavior and Chromattic provides it as well, as it has the benefit to use an input stream to read and write binary data which is efficient for large binary content. This approach does not force to hold all the data in memory, unlike the byte array approach. However it requires a little extra work from the developer to use the input stream carefully.

To read the data, the property getter returns an input stream that provides access to the binary data. The stream should be used as any other kind of input stream: consume data until the stream is empty and then close the stream in a finally block. The stream must be used corrected, otherwise the entire content could be loaded in memory and that would defeat the purpose of the stream based approach.

To write data, the property setter must be called with an input stream that is used to consume all the data available. It means that on the return of the setter, the input stream shouldn't be used anymore for reading data as Chromattic will close the stream. Again here, the stream must be used carefully.

The types BOOLEAN, LONG and DOUBLE are mapped to Java primitive types:

For each of those types, there is the choice between either the Java primitive type or the Java wrapper type.

JCR defines a DATE type that represents a date. Chromattic provides three different mappings for this type:

Date objects objects are mutable by nature and Chromattic clones them when it is necessary to preserve the data. A date object returned by Chromattic can be modified without changing mapped JCR value, likewise a property update will read the value once and copy it.

The most common mapping style between a single valued class and a node property. The object property must provide at least a setter method or a getter method, probably both in most use cases, those methods must use the same java property type.

A property getter method returns the JCR property value. If the property does not exist, the null value is returned when the java property type is not a primitive type. Sometimes it can happen that the JCR property does not exist but this property is mapped to a primitive type. When the situation occurs Chromattic throws a NullPointerException, that behavior is similar to what happens when a null value is unboxed to its corresponding primitive type.

A property setter method updates the JCR property value when it is invoked. For non primitive type it is possible to delete the property by providing a null argument.

  /**
   * Returns the page title.
   *
   * @return the page title
   */
  @Property(name = "title")
  public abstract String getTitle();  

  /**
   * Updates the page title.
   *
   * @param title the new page title
   */
  public abstract void setTitle(String title);

  /**
   * Returns the date of the page last modification.
   *
   * @return the date of the last modification
   */
  @Property(name = "lastmodifieddate")
  public abstract Date getLastModifiedDate();  

  /**
   * Updates the date of the page last modification.
   *
   * @param date the date of the last modification
   */
  public abstract void setLastModifiedDate(Date date);

	The title property is mapped the STRING type
	the last modified date property is mapped to the DATE type

The corresponding JCR node defines a title property and lastModifiedDate property:

<propertyDefinition autoCreated="false" mandatory="false" multiple="false" name="title" onParentVersion="COPY" protected="false" requiredType="String">
  <valueConstraints/>
</propertyDefinition>
<propertyDefinition autoCreated="false" mandatory="false" multiple="false" name="lastmodifieddate" onParentVersion="COPY" protected="false" requiredType="Date">
  <valueConstraints/>
</propertyDefinition>

JCR naturally provide support for multi valued properties, so does Chromattic. Chromattic gives you the choice to use either an array or a java.util.List to access the data. A primitive array can be used when the type is a primitive type.

  /**
   * Returns the list of the page tags.
   *
   * @return the list of tags
   */
  @Property(name = "tags")
  public abstract List<String> getTags();  

the tags property is mapped to a multi valued STRING type

The corresponding JCR node defines a tags properties:

<propertyDefinition autoCreated="false" mandatory="false" multiple="true" name="tags" onParentVersion="COPY" protected="false" requiredType="String">
  <valueConstraints/>
</propertyDefinition>

When a list of values is returned by a getter method, any modification to this list is only visible to this list and does not affect the JCR property values. When the JCR property does not exist, a null value is returned to the caller.

To update the values of a JCR property, the property setter has to be invoked. The list of values is read once and copied to the corresponding JCR property. If the list is null, it simply delete the property.

It can be convenient to map a single valued property to a multi valued property. For instance a multi valued JCR property exposed as a single valued property provides access to the first value of the values.

The same multi valued JCR property can be exposed both as a single and multi valued property. The multi valued property gives access to the complete list of values and the single valued property is useful when the first value needs to be accessed.

The list mapping must be only used when the corresponding node type has defined its children to be ordered. The list interface adds the notion of order to the collection interface, and using the order oriented method on the list will affect the order of the children.

children.add(children.get(0));

The map interface adds the notion of key which is very useful when the children needs to be accessed by their key. Previously we have seen that when the child is created from the session, its name has to be specifed. When the map interface is used, this is not necessary anymore, as the child name is specified when it is inserted with the put(String key, Page value) operation.

Page page = session.create(Page.class);
children.put("foo", page);

Page foo = children.get("foo");

children.remove("foo");