Each mapping definition in Compass is registered under an alias. The alias is used as the link between the OSEM definitions of a class, and the class itself. The alias can then be used to reference the mapping, both in other mapping definitions and when working directly with Compass API. When using annotations mappings, the alias defaults to the short class name.

There are two types of searchable classes in Compass, root searchable classes and non-root searchable classes. Root searchable classes are best defined as classes that return as hits when a search is performed. For example, in a scenario where we have Customer class with a Name class, the Customer will be a root searchable class, and Name would have root="false" in it since it does not "stands on its own". Another way of looking at root searchable classes is as searchable classes that end up marshaled into their own Resource (which is then used to work against the search engine).

Non root searchable classes are not required to define id mappings.

By default, each root searchable class will have its own sub index defaulting to the alias name. The sub index name can be controlled, allowing to join several root searchable classes into the same sub index, or using different sub index hashing functions. Please read Section 5.8, “Sub Index Hashing” for more information.

Each root searchable class must define at least one searchable id. The searchable id(s) are used to uniquely identify the object within its alias context. More than one searchable id can be defined, as well as user defined classes to act as searchable ids (must register its own converter or use searchable id component mapping).

Searchable Id does not require the definition of a searchable meta-data. If none is defined, Compass will automatically create an internal meta-data id (explained later) which most times is perfectly fine (usually, text searching based on the surrogate id is not required). If the searchable id does need to be searched, a searchable meta-data need to be defined for it. When using xml mapping, one or more meta-data element need to be added to the id element. When using annotations, there are three options: the first, provide a name for the SearchableId (compass will automatically act as if a SearchableMetaData was defined on the SearchableId and add it), the second is to add a SearchableMetaData annotation and the last is to add SearchableMetaDatas annotation (for multiple meta-datas). Of course, all the three can be combined. The reason why SearchalbeId will automatically create a SearchableMetaData if the name is provided is to ease the number of annotations required (and not get to annotation hell).

Here is an example of defining a Searchable Id using annotations. This example will not create any visible meta-data (as the SearchableId has no name to it, or SearchableMetaData(s) annotation).

@Searchable
public class Author {
  @SearchableId
  private Long id;  
  // ...
}

And here is the same mapping definition using xml:

<class name="Author" alias="author">
  <id name="id" />
  <!-- ... -->
</class>

The following is another example, now with actually defining a meta-data on the id for its values to be searchable:

@Searchable
public class Author {
  @SearchableId(name = "id")
  private Long id;  
  // ...
}

Which is the same as defining the following mapping using SearchableMetaData explicitly:

@Searchable
public class Author {
  @SearchableId
  @SearchableMetaData(name = "id")
  private Long id;  
  // ...
}

And here is the same mappings as above using xml:

<class name="Author" alias="author">
  <id name="id">
    <meta-data>id</meta-data>
  </id>
  <!-- ... -->
</class>

A searchable id component represent a composite object acting as the id of a object. It works in a similar manner to searchable component except that it will act as the id of the class.

Here is an example of defining a Searchable Id Component using annotations (note, in this case, B is not a root searchable class, and it needs to define only ids):

@Searchable
public class A {
  @SearchableIdComponent
  private B b;  
  // ...
}

@Searchable(root = false)
public class B {
  @SearchableId
  private long id1;
  
  @SearchableId
  private long id2;
}

And here is the same mapping definition using xml:

<class name="A" alias="a">
  <id-component name="b" />
  <!-- ... -->
</class>
<class name="B" alias="b" root="false">
  <id name="id1" />
  <id name="id2" />
</class>

Searchable Parent mapping provides support for cyclic mappings for components (though bi directional component mappings are also supported). If the component class mapping wish to map the enclosing class, the parent mapping can be used to map to it. The parent mapping will not marshal (persist the data to the search engine) the parent object, it will only initialize it when loading the parent object from the search engine.

Here is an example of defining a Searchable Component and Searchable Parent using annotations (note, in this case, B is not a root searchable class, and need not define any ids):

@Searchable
public class A {
  @SearchableId
  private Long id;
  @SearchableComponent
  private B b;  
  // ...
}

@Searchable(root = false)
public class B {
  @SearchableParent
  private A a;
  // ...
}

And here is the same mapping definition using xml:

<class name="A" alias="a">
  <id name="id" />
  <component name="b" />
  <!-- ... -->
</class>
<class name="B" alias="b" root="false">
  <parent name="a" />
  <!-- ... -->
</class>

A Searchable Property maps to a Class attribute/property which is a simple relationship. The searchable property maps to a class attribute that ends up as a String within the search engine. This include primitive types, primitive wrapper types, java.util.Date, java.util.Calendar and many more types that are automatically supported by Compass (please see the converter section). A user defined type can be used as well using a custom converter (though most times, a component relationship is more suited - explained later). A Searchable Mata Data uses the Searchable Property value (converted String value using its registered converter) and stores it in the index against a name.

When using xml mapping, one or more meta-data elements can be defined for a property mapping. When using annotation, a SearchableProperty needs to be defined on the mapped class attribute. A SearchableMetaData annotation can be explicitly defined, as well as SearchableMetaDatas (for multiple meta data). A SearchableProperty will automatically create a SearchableMetaData (in order not to get annotation hell) if no SearchableMetaData(s) annotation is defined, or a its name is explicitly defined (note, all the SearchableMetaData options are also defined on the SearchableProperty, they apply to the automatically created SearchableMetaData).

Here is an example of defining a Searchable Property using annotations. This example will automatically create a Searchable Meta Data with the name of value (the class field name).

@Searchable
public class Author {
  // ...
  @SearchableProperty
  private String value;  
  // ...
}

This mapping is the same as defining the following annotation using SearchableMetaData explicitly:

@Searchable
public class Author {
  // ...
  @SearchableProperty
  @SearchableMetaData(name = "value")
  private String value;  
  // ...
}

And here is the same mapping definition using xml:

<class name="Author" alias="author">
  <! ... -->
  <property name="value">
    <meta-data>value</meta-data>
  </property>
  <!-- ... -->
</class>

Searchable Constant allows to define constant meta data associated with a searchable class with a list of values set against a constant name. This is useful for adding static meta-data against a Searchable Class, allowing to create semantic groups across the searchable classes.

Here is how a searchable constant meta-data can be defined using annotations:

@Searchable
@SearchableConstant(name = "type", values = {"person", "author"})
public class Author {
} 

And here is how it can be defined using xml mappings:

<class name="Author" alias="author">
  <id name="id" />
  <constant>
    <meta-data>type</meta-data>
    <meta-data-value>person</meta-data-value>
    <meta-data-value>author</meta-data-value>
  </constant>
  <!-- ... -->
</class>

The dynamic meta data mapping allows to define meta-data saved into the search engine as a result of evaluating an expression. The mapping does not map to any class property and acts as a syntactic meta-data (similar to the constant mapping). The value of the dynamic meta-data tag is the expression evaluated by a Dynamic Converter. Compass comes with several built in dynamic converters: el (Jakarta commons el), jexl (Jakarta commons jexl), velocity, ognl, and groovy. When defining the expression, the root class is registered under the data key (for libraries that require it).

Here is an example of how to define a searchable dynamic meta-data (with jakarta commons jexl) using annotations (assuming class A has value1 and value2 as class fields):

@Searchable
@SearchableDynamicMetaData(name = "test", expression = "data.value + data.value2", converter = "jexl")
public class A {
} 

And here is the same mapping using xml:

<class name="Author" alias="author">
  <id name="id" />
  <dynamic-meta-data name="test" converter="jexl">
      data.value + data.value2
  </dynamic-meta-data>
  <!-- ... -->
</class>

A searchable reference mapping maps between one root searchable class and the other. The mapping is only used for keeping the relationship "alive" when performing un-marshalling. The marshalling process marshals only the referenced object ids (based on its id mappings) and use it later in the un-marshalling process to load the referenced object from the index.

Cascading is supported when using reference mappings. Cascading can be configured to cascade any combination of create/save/delete operations, or all of them. By default, no cascading will be performed on the referenced object.

In order to identify the referenced class mapping, Compass needs access to its class mapping definition. In most cases there is no need to define the referenced alias that define the class mapping, as Compass can automatically detect it. If it is required, it can be explicitly set on the reference mappings (an example when Compass needs this mapping is when using Collection without generics or when a class has more than one class mapping).

Currently, Compass does not support lazy loading, this means that when loading a searchable class, all its referenced mappings will be loaded as well.

Here is an example of defining a Searchable Reference using annotations:

@Searchable
public class A {
  @SearchableId
  private Long id;
  @SearchableReference
  private B b;  
  // ...
}

@Searchable
public class B {
  @SearchableId
  private Long id;
  // ...
}

And here is the same mapping definition using xml:

<class name="A" alias="a">
  <id name="id" />
  <reference name="b" />
  <!-- ... -->
</class>
<class name="B" alias="b">
  <id name="id" />
  <!-- ... -->
</class>

A searchable component mapping embeds a searchable class within its owning searchable class. The mapping is used to allow for searches that "hit" the component referenced searchable class to return the owning searchable class (or its parent if it also acts a component mapping up until the root object that was saved).

The component referenced searchable class can be either root or not. An example for a non root component can be a Person class (which is root) with a component mapping to a non root searchable class Name (with firstName and lastName fields). An example for a root component can be a Customer root searchable class and an Account searchable class, where when searching for account details, both Account and Customer should return as hits.

Cascading is supported when using component mappings. Cascading can be configured to cascade any combination of create/save/delete operations, or all of them. By default, no cascading will be performed on the referenced object. Cascading can be performed on non root objects as well, which means that a non root object can be "created/saved/deleted" in Compass (using save operation) and Compass will only cascade the operation on its referenced objects without actually performing the operation on the non root object.

In order to identify the referenced component class mapping, Compass needs access to its class mapping definition. In most cases there is no need to define the referenced alias that define the class mapping, as Compass can automatically detect it. If it is required, it can be explicitly set on the reference mappings (an example when Compass needs this mapping is when using Collection without generics or when a class has more than one class mapping).

Here is an example of defining a Searchable Component using annotations (note, in this case, B is not a root searchable class, and need not define any ids):

@Searchable
public class A {
  @SearchableId
  private Long id;
  @SearchableComponent
  private B b;  
  // ...
}

@Searchable(root = false)
public class B {
  // ...
}

And here is the same mapping definition using xml:

<class name="A" alias="a">
  <id name="id" />
  <component name="b" />
  <!-- ... -->
</class>
<class name="B" alias="b" root="false">
  <!-- ... -->
</class>

The searchable cascading mapping allows to define cascading operations on certain properties without explicitly using component/reference/parent mappings (which have cascading option on them). Cascading actually results in a certain operation (save/delete/create) to be cascaded to and performed on the referenced objects.

Here is an example of a Searchable Cascade mapping based on the class language:

@Searchable
public class A {
  @SearchableId
  private Long id;
  @SearchableCascading(cascade = {Cascade.ALL})
  private B b;  
  // ...
}

And here is the same mapping definition using xml:

<class name="A" alias="a">
  <id name="id" />
  <cascade name="b" cascade="all" />
  <!-- ... -->
</class>

The searchable analyzer mapping dynamically controls the analyzer that will be used when indexing the class data. If the mapping is defined, it will override the class mapping analyzer attribute setting.

If, for example, Compass is configured to have two additional analyzers, called an1 (and have settings in the form of compass.engine.analyzer.an1.*), and another called an2. The values that the searchable analyzer can hold are: default (which is an internal Compass analyzer, that can be configured as well), an1 and an2. If the analyzer will have a null value, and it is applicable with the application, a null-analyzer can be configured that will be used in that case. If the class property has a value, but there is not matching analyzer, an exception will be thrown.

Here is an example of a Searchable Analyzer mapping based on the class language:

@Searchable
public class A {
  @SearchableId
  private Long id;
  @SearchableAnalyzer
  private String language;  
  // ...
}

And here is the same mapping definition using xml:

<class name="A" alias="a">
  <id name="id" />
  <analyzer name="language" />
  <!-- ... -->
</class>

The searchable boost mapping dynamically controls the boost value associated with the Resource stored. If the mapping is defined, it will override the class mapping boost attribute setting. The value of the property should be convertable to float value.

Here is an example of a Searchable Analyzer mapping based on the class language:

@Searchable
    public class A {
      @SearchableId
      private Long id;
      @SearchableBoost(defaultValue = 2.0f)
      private Float value;  
      // ...
    }

And here is the same mapping definition using xml:

<class name="A" alias="a">
      <id name="id" />
      <boost name="value" default="2.0" />
      <!-- ... -->
    </class>
    

Collection (java.util.Collection) based types cab be mapped using Searchable Property, Searchable Component and Searchable Reference. The same mapping declaration should be used, with Compass automatically detecting that a java.util.Collection is being mapped, and applying the mapping definition to the collection element.

When mapping a Collection with a Searchable Property, Compass will try to automatically identify the collection element type if using Java 5 Generics. If Generics are not used, the class attribute should be set with the FQN of the element class. With Searchable Component or Reference Compass will try to automatically identify the referenced mapping if Generics are used. If generics are not used the ref-alias should be explicitly set.

When marshaling an Object into a search engine, Compass might add internal meta-data for certain Searchable Properties in order to properly un-marshall it correctly. Here is an example mapping where an internal meta-data id will be created for the firstName and lastName searchable properties:

@Searchable
public class A {
  @SearchableId
  private Long id;
  @SearchableProperty(name = "name")
  private String lastName;  
  @SearchableProperty(name = "name")
  private String firstName;  
  @SearchableProperty
  private String birthdate;  
}

In the above mapping we map firstName and lastName into "name". Compass will automatically create internal meta-data for both firstName and lastName, since if it did not create one, it won't be able to identify which name belongs to which. Compass comes with three strategies for creating internal meta-data:

Setting the managed id can be done on several levels. It can be set on the property mapping level explicitly. It can be set on the class level mapping which will then be applied to all the properties that are not set explicitly. And it can also be set globally be setting the following setting compass.osem.managedId which will apply to all the classes and properties that do not set it explicitly. By default, it is set to NO_STORE.

There are different strategies when mapping an inheritance tree with Compass. The first apply when the inheritance tree is known in advance. If we take a simple inheritance of class A and class B that extends it, here is the annotation mapping that can be used for it:

@Searchable
public class A {
  @SearchableId
  private Long id;
  @SearchableProperty
  private String aValue;
}

@Searchable
public class B extends A {
  @SearchableProperty
  private String bValue;
}

Compass will automatically identify that B extends A, and will include all of A mapping definitions (note that Searchable attributes will not be inherited). When using annotations, Compass will automatically interrogate interfaces as well for possible Searchable annotations, as well have the possibility to explicitly define which mappings to extend using the extend attribute (the mappings to extends need not be annotation driven mappings).

When using xml mapping definition, the above inheritance tree can be mapped as follows:

<class name="A" alias="a">
  <id name="id" />
  <property name="aValue">
    <meta-data>aValue</meta-data>
  </property>
</class>
<class name="B" alias="b" extends="a">
  <property name="bValue">
    <meta-data>aValue</meta-data>
  </property>
</class>

When using extends explicitly (as needed when using xml mappings), a list of the aliases to extend (comma separated) can be provided. All the extended mapping definitions will be inherited except for class mapping attributes.

If the inheritance tree is not known in advance, a poly flag should be set on all the known mapped inheritance tree. Compass will be able to persist unknown classes that are part of the mapped inheritance tree, using the closest searchable mapping definition. Here is an example of three classes: A and B are searchable classes, with B extending A. C extends B but is not a searchable class and we would still like to persist it in the search engine. The following is the annotation mappings for such a relationship:

@Searchable(poly = true)
public class A {
  // ...
}

@Searchable(poly = true)
public class B extends A {
  // ...
}

// Note, No Searchable annotation for C
public class C extends B {
  // ...
}

And here is the xml mapping definition:

<class name="A" alias="a">
  <id name="id" />
  <property name="aValue">
    <meta-data>aValue</meta-data>
  </property>
</class>
<class name="B" alias="b" extends="a">
  <property name="bValue">
    <meta-data>aValue</meta-data>
  </property>
</class>

When saving an Object of class C, B mapping definitions will be used to map it to the search engine. When loading it, an instance of class C will be returned, with all of its B level attributes initialized.

Polymorphic relationship are applicable when using component or reference mappings. If we take the following polymorphic relationship of a Father class to a Child class, with a Son and Daughter sub classes, the component/reference mapping relationship between Father and Child is actually a relationship between Father and Child, Son and Daughter. The following is how to map it using annotations:

@Searchable
public class Father {
  // ...
  @SearchableComponent
  private Child child;
}

@Searchable(poly = true)
public class Child {
  // ...
}

@Searchable(poly = true)
public class Son extends Child {
  // ...
}

@Searchable(poly = true)
public class Daughter extends Child {
  // ...
}

Compass will automatically identify that Child mappings has a Son and a Daughter, and will add them to the ref-alias definition of the SearchableComponent (similar to automatically identifying the mapping of Child). Explicit definition of the referenced aliases can be done by providing a comma separated list of aliases (this will disable Compass automatic detection of related classes and will only use the provided list). Note as well, that the Child hierarchy had to be defined as poly.

Here is the same mapping using xml:

<class name="Father" alias="father">
  <id name="id" />
  <component name="child" />
</class>
<class name="Child" alias="chlid" poly="true">
  <!-- ... -->
</class>
<class name="Son" alias="son" poly="true" extends="child">
  <!-- ... -->
</class>
<class name="Daughter" alias="daughter" poly="true" extends="child">
  <!-- ... -->
</class>

Compass OSEM fully supports cyclic relationships both for reference and component mappings. Reference mappings are simple, they are simply defined, and Compass would handle everything if they happen to perform a cyclic relationship.

Bi directional component mappings are simple as well with Compass automatically identifying cyclic relationship. A tree based cyclic relationship is a bit more complex (think of a file system tree like relationship). In such a case, the depth Compass will traverse with the component mapping is controlled using the max-depth attribute (defaults to 1).

Compass allows for Annotations and Xml mappings definitions to be used together. Annotations mappings can extend/override usual cpm.xml mapping definition (event extending xml contract mapping). When using annotations, a .cpm.ann.xml can be defined that will override annotations definitions using xml definitions.

Compass adds an overhead both in terms of memory consumption, processing speed and index size (managed ids) when it works in a mode that needs to support un-marshalling (i.e. getting objects back from the search engine). Compass can be configured not to support un-marshalling. In such a mode it will not add any internal Compass information to the index, and will use less memory. This setting can be a global setting (set within Compass configuration), or per searchable class definitions.

Though initially this mode may sounds unusable, it is important to remember that when working with support unmarshall set to false, the application can still use Compass Resource level access to the search engine. An application that works against the database using an ORM tool for example, might only need Compass to index its domain model into the search engine, and display search results. Displaying search results can be done using Resources (many times this is done even when using support for unmarshalling). Create/Delete/Update operations will be done based on ORM based fetched objects, and mirrored (either explicitly or implicitly) to the search engine.

Compass also allows using annotation for certain configuration settings. The annotations are defined on a package level (package-info.java). Some of the configuration annotations are @SearchAnalyzer, @SearchAnalyzerFilter, and @SearchConverter. Please see the javadocs for more information.

The main element which holds all the rest of the mappings definitions.

<compass-core-mapping package="packageName"/>
        

Declaring a searchable class using the class element.

<class
        name="className"
        alias="alias"
        sub-index="sub index name"
        analyzer="name of the analyzer"
        root="true|false"
        poly="false|true"
        poly-class="the class name that will be used to instantiate poly mapping (optional)"
        extends="a comma separated list of aliases to extend"
        support-unmarshall="true|false"
        boost="boost value for the class"
        converter="converter lookup name"
>
    all?,
    sub-index-hash?.
    (id)*,
    parent?,
    (analyzer?),
    (boost?),
    (property|dynamic-meta-data|component|reference|constant)*
</class>

Root classes have their own index within the search engine index directory (by default). Classes with a dependency to Root class, that don't require an index (i.e. component) should set root to false. You can control the sub-index that the root classes will map to using the sub-index attribute or the sub-index-hash element, otherwise it will create a sub-index based on the alias name.

The class mapping can extend other class mappings (more than one), as well as contract mappings. All the mappings that are defined within the class mapping or the contract mapping will be inherited from the extended mappings. You can add any defined mappings by defining the same mappings in the class mappings, except for id mappings, which will be overridden. Note that any xml attributes (like root, sub-index, ...) that are defined within the extended mappings are not inherited.

The default behavior of the searchable class will support the "all" feature, which means that compass will create an "all" meta-data which represents all the other meta-data (with several exceptions, like Reader class property). The name of the "all" meta-data will default to the compass setting, but you can also set it using the all-metadata attribute.

Declaring a searchable contract using the contract element.

<contract
        alias="alias"
>
    (id)*,
    (analyzer?),
    (boost?),
    (property|dynamic-meta-data|component|reference|constant)*
</contract>

A contract acts as an interface in the Java language. You can define the same mappings within it that you can define in the class mapping, without defining the class that it will map to.

If you have several classes that have similar properties, you can define a contract that joins the properties definition, and than extend the contract within the mapped classes (even if you don't have a concrete interface or class in your Java definition).

Declaring a searchable id class property (a.k.a JavaBean property) of a class using the id element.

<id
      name="property name"
      accessor="property|field"
      boost="boost value for the class property"
      class="explicit declaration of the property class"
      managed-id="auto|true|false"
      managed-id-converter="managed id converter lookup name"
      exclude-from-all="no|yes|no_analyzed"
      converter="converter lookup name"
  >
 (meta-data)*
</id>

The id mapping is used to map the class property that identifies the class. You can define several id properties, even though we recommend using one. You can use the id mapping for all the Java primitive types (i.e. int), Java primitive wrapper types (i.e. Integer), String type, and many other custom types, with the only requirement that a type used for an id will be converted to a single String.

Declaring a searchable class property (a.k.a JavaBean property) of a class using the property element.

<property
      name="property name"
      accessor="property|field"
      boost="boost value for the property"
      class="explicit declaration of the property class"
      analyzer="name of the analyzer"
      override="true|false"
      managed-id="auto|true|false"
      managed-id-index="[compass.managedId.index setting]|no|un_tokenized"
      managed-id-converter="managed id converter lookup name"
      exclude-from-all="no|yes|no_analyzed"
      converter="converter lookup name"
>
   (meta-data)*
</property>

You can map all internal Java primitive data types, primitive wrappers and most of the common Java classes (i.e. Date and Calendar). You can also map Arrays and Collections of these data types. When mapping a Collection, you must specify the object class (like java.lang.String) in the class mapping property (unless you are using generics).

Note, that you can define a property with no meta-data mapping within it. It means that it will not be searchable, but the property value will be stored when persisting the object to the search engine, and it will be loaded from it as well (unless it is of type java.io.Reader).

Declaring an analyzer controller property (a.k.a JavaBean property) of a class using the analyzer element.

<analyzer
      name="property name"
      null-analyzer="analyzer name if value is null"
      accessor="property|field"
      converter="converter lookup name"
>
</analyzer>

The analyzer class property mapping, controls the analyzer that will be used when indexing the class data (the underlying Resource). If the mapping is defined, it will override the class mapping analyzer attribute setting.

If, for example, Compass is configured to have two additional analyzers, called an1 (and have settings in the form of compass.engine.analyzer.an1.*), and another called an2. The values that the class property can hold are: default (which is an internal Compass analyzer, that can be configured as well), an1 and an2. If the analyzer will have a null value, and it is applicable with the application, a null-analyzer can be configured that will be used in that case. If the class property has a value, but there is not matching analyzer, an exception will be thrown.

Declaring boost property (a.k.a JavaBean property) of a class using the boost element.

<boost
      name="property name"
      default="the boost default value when no property value is present"
      accessor="property|field"
      converter="converter lookup name"
>
</boost>

The boost class property mapping, controls the boost associated with the Resource created based on the mapped property. The value of the property should be allowed to be converted to float.

Declaring and using the meta-data element.

<meta-data
      store="yes|no|compress"
      index="tokenized|un_tokenized|no"
      boost="boost value for the meta-data"
      analyzer="name of the analyzer"
      reverse="no|reader|string"
      null-value="String value that will be stored when the property value is null"
      exclude-from-all="[parent's exclude-from-all]|no|yes|no_analyzed"
      converter="converter lookup name"
      term-vector="no|yes|positions|offsets|positions_offsets"
      format="the format string (only applies to formatted elements)"
>
</meta-data>

The element meta-data is a Property within a Resource.

You can control the format of the marshalled values when mapping a java.lang.Number (or the equivalent primitive value) using the format provided by the java.text.DecimalFormat. You can also format a java.util.Date using the format provided by java.text.SimpleDateFormat. You set the format string in the format attribute.

Declaring and using the dynamic-meta-data element.

<dynamic-meta-data
      name="The name the meta data will be saved under"
      store="yes|no|compress"
      index="tokenized|un_tokenized|no"
      boost="boost value for the meta-data"
      analyzer="name of the analyzer"
      reverse="no|reader|string"
      null-value="optional String value when expression is null"
      exclude-from-all="[parent's exclude-from-all]|no|yes|no_analyzed"
      converter="the Dynamic Converter lookup name (required)"
      format="the format string (only applies to formatted elements)"
>
</meta-data>

The dynamic meta data mapping allows to define meta-data saved into the search engine as a result of evaluating an expression. The mapping does not map to any class property and acts as a syntactic meta-data (similar to the constant mapping). The value of the dynamic meta-data tag is the expression evaluated by a Dynamic Converter. Compass comes with several built in dynamic converters: el (Jakarta commons el), jexl (Jakarta commons jexl), velocity, ognl, and groovy. When defining the expression, the root class is registered under the data key (for libraries that require it).

Declaring and using the component element.

<component
      name="the class property name"
      ref-alias="name of the alias"
      max-depth="the depth of cyclic component mappings allowed"
      accessor="property|field"
      converter="converter lookup name"
      cascade="comma separated list of create,save,delete or all"
>
</component>

The component element defines a class dependency within the root class. The dependency name is identified by the ref-alias, which can be non-rootable or have no id mappings.

An embedded class means that all the mappings (meta-data values) defined in the referenced class are stored within the alias of the root class. It means that a search that will hit one of the component mapped meta-datas, will return it's owning class.

The type of the JavaBean property can be the class mapping class itself, an Array or Collection.

Declaring and using the reference element.

<reference
        name="the class property name"
        ref-alias="name of the alias"
        ref-comp-alias="name of an optional alias mapped as component"
        accessor="property|field"
        converter="converter lookup name"
        cascade="comma separated list of create,save,delete or all"
  >
</reference>

The reference element defines a "pointer" to a class dependency identified in ref-alias.

The type of the JavaBean property can be the class mapping class itself, an Array of it, or a Collection.

Currently there is no support for lazy behavior or cascading. It means that when saving an object, it will not persist the object defined references and when loading an object, it will load all it's references. Future versions will support lazy and cascading features.

Compass supports cyclic references, which means that two classes can have a cyclic reference defined between them.

Declaring and using the parent element.

<parent
        name="the class property name"
        accessor="property|field"
        converter="converter lookup name"
  >
</reference>

The parent mapping provides support for cyclic mappings for components (though bi directional component mappings are also supported). If the component class mapping wish to map the enclosing class, the parent mapping can be used to map to it. The parent mapping will not marshal (persist the data to the search engine) the parent object, it will only initialize it when loading the parent object from the search engine.

Declaring a constant set of meta-data using the constant element.

<constant
          exclude-from-all="no|yes|no_analyzed"
          converter="converter lookup name"
    >
   meta-data,
   meta-data-value+
</reference>

If you wish to define a set of constant meta data that will be embedded within the searchable class (Resource), you can use the constant element. You define the usual meta-data element followed by one or moremeta-data-value elements with the value that maps to the meta-data within it.