# SOLRJ extensions for the Castor XML code generator

## SOLRJ extensions - Motivation

With Castor 1.2 and previous releases it was already possible to generate Java classes from an XML schema and use these classes for XML data binding without having to write a mapping file.

This is possible because the Castor XML code generator generated - in addition to the domain classes - a set of XML descriptor classes as well, with one descriptor class generated per generated domain class. It's this XML descriptor class that holds all the information required to map Java classes and/or field members to XML artifacts, as set out in the original XML schema definitions. This includes ....

- artefact names

- XML namespace URIs

- XML namespace prefix

- validation code

The SOLRJ extensions for the Castor XML code generator extend the code generator in such a way that the set of domain classes is augmented with SOLRJ-specific `@Field` annotations.

The following sections introduce the general principles, define the XML schema artifacts available to annotate an existing XML schema and highlight the usage of these artifacts by providing examples.

## Prerequisites

To facilitate the detailed explanations in the following sections, we now define a few <complexType> definitions that we want to be able to store in a SOLR index in addition to vanilla XML data binding funtionality.

### Sample XML schemas

    <complexType name="bookType">
       <sequence>
          <element name="isbn" type="xs:string" />
          <element name="pages" type="xs:integer" />
       </sequence>
    </complexType>

## The SOLRJ annotations for XML schemas

This section enlists the XML artifacts available to annotate an existing XML schema with SOLRJ extension-specific information. These constructs are defined themselves in an XML schema `solrj-extensions.xsd` that has a target namespace of http://www.castor.org/binding/solrj.

To enable proper validation of your XML schemas when editing SOLRJ annotations, and to enable XML completion in your preferred XML editor, please add `schemaLocation` information to your XML schema definition as follows:

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
        targetNamespace="http://your/target/namespace"
        xmlns:solr="http://www.castor.org/binding/solrj"
        xmlns="http://your/target/namespace"
        xsi:schemaLocation="http://www.castor.org/binding/solrj http://www.castor.org/solrj-extensions.xsd">

    ...

    </xs:schema>

where ...

The values supplied in the `schemaLocation` attribute define the location of the XML schema for any XML artefacts bound to the `http://www.castor.org/binding/solrj` namespace.

### <field> element

The <field> element allows you to map a member of the content model of a `<complexType>` definition to SOLRJ field.

    <complexType name="bookType">
       <sequence>
          <element name="isbn" type="xs:string">
             <xs:annotation>
                <xs:appinfo>
                    <solrj:field name="id" />
                </xs:appinfo>
             </xs:annotation>
          </element>
          <element name="pages" type="xs:integer">
             <xs:annotation>
                <xs:appinfo>
                    <solrj:field />
                </xs:appinfo>
             </xs:annotation>
          </element>
       </sequence>
    </complexType>

where ....

Defines that the element definition `isbn` be mapped against the SOLRJ field `id`.

Defines that the element definition `name` be mapped to the SOLRJ field `name`.

Above example maps the element `isbn` to the SOLR index field `id`, and the element `name` to the identically-named SOLR index field. Please note that a SOLR index field name does not have to be specified if the field name and the Java property name are identical.

Above complex type definition will be transformed to the corresponding Java property definitions (within a class):

    public class BookType {

        @Field("id")
        private String isbn;

        @Field
        private long pages;

    }

The XML schema definition for `<field>` is defined as follows:

    <xs:element name="field">
      <xs:annotation>
         <xs:documentation>
                Element 'field' is used to specify the use of the SOLRJ
                @Field annotation.
            </xs:documentation>
      </xs:annotation>
      <xs:complexType>
         <xs:attribute name="name" type="xs:string" use="optional">
            <xs:annotation>
               <xs:documentation>
                        Attribute 'name' is used to specify the name of
                        the index field to be mapped against; if not used,
                        the name of the Java property will be used as filed
                        name.
                    </xs:documentation>
            </xs:annotation>
         </xs:attribute>
      </xs:complexType>
    </xs:element>

where the content is described as follows:

<field> - Definitions

Name | Description | Optional?
--- | --- | ---
name | Name of the SOLR index field. | Yes

## Using the generated domain classes with SOLR

Once you have generated domain classes (and descriptor classes for the XML binding) from your set of XML schemas, you'll be able to use them as are.