Author has an implicit default (no-argument) constructor. All persistent classes must have a default constructor (which may be non-public) so Compass::Core can instantiate using Constructor.newInstance().

OSEM requires that any mapped Object will define one or more properties (JavaBean properties) that identifies the class. The id properties can be called anything, and it's type can be any primitive type, primitive "wrapper" type, java.lang.String or java.util.Date.

Even though Compass can directly persist instance variables, it is usually better to decouple this implementation detail from the Search Engine mechanism. Compass::Core recognizes JavaBean style property (getFoo, isFoo, and setFoo). This mechanism works with any level of visibility.

You have to override the equals() and hashCode() methods if you intend to mix objects of persistent classes (e.g. in a Set). You can implement it by using the identifier of both objects, but note that Compass::Core works best with surrogate identifier (and will provide a way to automatically generate them), thus it is best to implement the methods using business keys.

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"
        extends="a comma seperated list of aliases to extend"
        boost="boost value for the class"
        all="true|false"
        all-term-vector="no|yes|positions|offsets|positios_offsets"
        all-metadata="all meta-data"
        all-analyzer="name of the analyzer used for the all proeprty"
        converter="fully qualified converter class name|converter lookup name"
        converter-param="parameter for the converter"
>
    (converter-param)*,
    (id)*,
    parent?,
    (analyzer?),
    (property|component|reference|constant)*
</class>

Root classes have their own index within the search engine index directory. 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, otherwise it will create a sub-index based on the alias name.

If the class can be mapped to several classes (i.e. it is an interface or an abstract class), than set poly to true. This means Compass will persist the fully qualified class in the index.

You can set the boost level at the class level, which is applied to all class meta data (override by specifying at meta data level).

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.

Compass provides support for custom converters. Please refer to the converter section later on.

Declaring a searchable contract using the contract element.

<contract
        alias="alias"
>
    (id)*,
    (analyzer?),
    (property|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"
      exclude-from-all="false|true"
      converter="fully qualified converter class name|converter lookup name"
      converter-param="parameter for the converter"
  >
 (converter-param)*,
 (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) and the String type.

Compass::Core requires that id and property mappings will be identifiable on the root class (Resource) level. Compass does that by either using one of the meta-data names (which is unique within ALL of the meta-data in the class mapping), or creating an internal one. Compass will create an internal one if no meta-data is defined in the id or property mapping. You can control it by using the managed-id, the value auto leaves the id assignment / creation as Compass's responsibility. Compass will analyse all the different meta- data defined in the mappings and will decide if it needs to create an internal id for an id or a property mapping. The true option will always create an internal id for the id or property and the false option will always take the first meta-data and use it as the id or property id.

Compass provides support for custom converters. Please refer to the converter section later on.

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"
      managed-id="auto|true|false"
      managed-id="[compass.managedId.index setting]|no|un_tokenized"
      exclude-from-all="false|true"
      col-class="fully qualified class of the collection class"
      converter="fully qualified converter class name|converter lookup name"
      converter-param="parameter for the converter"
>
   (converter-param)*,
   (meta-data)*
</property>

Compass::Core maps a class property to a set of meta-data (Resource Property).

You can map all internal Java primitive data types, primitive wrapper 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.

The same rules for managed-id that apply for the id mapping, also applies for property mappings.

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).

Compass provides support for custom converters. Please refer to the converter section later on.

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="fully qualified converter class name|converter lookup name"
      converter-param="parameter for the converter"
>
</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, than 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 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"
      exclude-from-all="[parent's exclude-from-all]|false|true"
      converter="fully qualified converter class name|converter lookup name"
      converter-param="parameter for the converter"
>
   (converter-param)*,
</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 converter-param attribute.

Declaring and using the component element.

<component
      name="the class property name"
      ref-alias="name of the alias"
      accessor="property|field"
      converter="fully qualified converter class name|converter lookup name"
      converter-param="parameter for the converter"
>
   (converter-param)*,
</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.

Support for cyclic mapping (from one component to it's parent class) is implemented using the parent mapping.

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="fully qualified converter class name"
        converter-param="parameter for the converter"
  >
 (converter-param)*,
</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::Core 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="fully qualified converter class name"
        converter-param="parameter for the converter"
  >
 (converter-param)*,
</reference>

The parent mapping provides support for cyclic mappings for components. 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="false|true"
          converter="fully qualified converter class name"
          converter-param="parameter for the converter"
    >
   (converter-param)*,
   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.

Compass::Core uses converters to convert all the different types and mappings. Compass::Core has default converters for most of your needs, you can define your own using the converter attribute where appropriate. If your converter requires parameters, you can use the converter-param attribute or the converter-param elements.