spring-data-neo4j/src/docbkx/reference/programming-model/node-entities.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<section id="reference:programming-model:annotations">
    <title>Defining node entities</title>
    <para>
        Node entities are declared using the <code>@NodeEntity</code> annotation. Relationship entities use
        the <code>@RelationshipEntity</code> annotation.
    </para>
    <section>
        <title>@NodeEntity: The basic building block</title>
        <para>
            The <code>@NodeEntity</code> annotation is used to turn a POJO class into an entity backed by a node
            in the graph database. Fields on the entity are by default mapped to properties of the node. Fields
            referencing other node entities (or collections thereof) are linked with relationships. If the
            <code>useShortNames</code> attribute overridden to false, the property and relationship names will
            have the class name of the entity prepended.
        </para>
        <para>
            <code>@NodeEntity</code> annotations are inherited from super-types and interfaces. It is not necessary
            to annotate your domain objects at every inheritance level.
        </para>
        <para>
            If the <code>partial</code> attribute is set to true, this entity takes part in a cross-store setting,
            where the entity lives in both the graph database and a JPA data source. See
            <xref linkend="cross-store"/> for more information.
        </para>
        <para>
            Entity fields can be annotated with <code>@GraphProperty</code>, <code>@RelatedTo</code>,
            <code>@RelatedToVia</code>, <code>@Indexed</code>, <code>@GraphId</code> and
            <code>@GraphTraversal</code>.
        </para>
        <example>
            <title>Simple node entity</title>
            <programlisting language="java"><![CDATA[@NodeEntity
public class Movie {
    String title;
}
]]></programlisting>
        </example>
    </section>

    <section>
        <title>@GraphProperty: Optional annotation for property fields</title>
        <para>
            It is not necessary to annotate data fields, as they are persisted by default; all fields that
            contain primitive values are persisted directly to the graph. All fields convertible to String
            using the Spring conversion services will be stored as a string. Spring Data Neo4j includes a
            custom conversion factory that comes with converters for <code>Enum</code>s and <code>Date</code>s.
            Transient fields are not persisted.
        </para>
        <para>
            Currently there is no support for handling arbitrary collections of primitive or convertable values.
            Support for this will be added by the 1.1. release.
        </para>
        <para>
            This annotation is typically used with cross-store persistence. When a node entity is configured
            as partial, then all fields that should be persisted to the graph must be explicitly annotated
            with <code>@GraphProperty</code>.
        </para>
    </section>

    <section>
        <title>@Indexed: Making entities searchable by field value</title>
        <para>
            The @Indexed annotation can be declared on fields that are intended to be indexed by the Neo4j
            indexing facilities. The resulting index can be used to later retrieve nodes or relationships
            that contain a certain property value, e.g. a name. Often an index is used to establish the start
            node for a traversal. Indexes are accessed by a repository for a particular node or relationship
            entity type. See <xref linkend="reference:programming-model:indexing"/> and
            <xref linkend="reference:programming-model:repositories"/> for more information.
        </para>
    </section>

    <section>
        <title>@Query: fields as query result views</title>
        <para>
            The <code>@Query</code> annotation leverages the delegation infrastructure used by the
            Spring Data Neo4j aspects. It provides dynamic fields which, when accessed, return the values
            selected by the provided query language expression. The provided query must contain a placeholder named <code>%start</code>
            for the id of the current entity. For instance <code>start n=(%start) match n-[:FRIEND]->friend return friend</code>.
            Graph queries can return variable number of entities. That's why annotation can be put onto fields
            with a single value, an Iterable of a concrete type or an Iterable of <code>Map&lt;String,Object&gt;</code>.
            Additional parameters are taken from the params attribute of the <code>@Query</code> annotation.
            The tuples form key-value pairs that are provided to the query at execution time.
        </para>
        <example>
            <title>@Graph on a node entity field</title>
            <programlisting language="java"><![CDATA[@NodeEntity
public class Group {
    @Query(value = "start n=(%start) match (n)-[:%relType]->(friend) return friend",
                params = {"relType", "FRIEND"})
    private Iterable<Person> friends;
}
]]></programlisting>

        </example>
        <para>
            <note>
                Please note that this annotation can also be used on repository methods.
            </note>
        </para>
    </section>
    <section>
        <title>@GraphTraversal: fields as traversal result views</title>
        <para>
            The <code>@GraphTraversal</code> annotation leverages the delegation infrastructure used by the
            Spring Data Neo4j aspects. It provides dynamic fields which, when accessed, return an Iterable
            of node entities that are the result of a traversal starting at the entity containing the field.
            The <code>TraversalDescription</code> used for this is created by the
            <code>FieldTraversalDescriptionBuilder</code> class defined by the <code>traversalBuilder</code>
            attribute. The class of the resulting node entities must be provided with the
            <code>elementClass</code> attribute.
        </para>
        <example>
            <title>@GraphTraversal from a node entity</title>
            <programlisting language="java"><![CDATA[@NodeEntity
public class Group {
    @GraphTraversal(traversalBuilder = PeopleTraversalBuilder.class,
            elementClass = Person.class, params = "persons")
    private Iterable<Person> people;

    private static class PeopleTraversalBuilder implements FieldTraversalDescriptionBuilder {
        @Override
        public TraversalDescription build(NodeBacked start, Field field, String... params) {
            return new TraversalDescriptionImpl()
                    .relationships(DynamicRelationshipType.withName(params[0]))
                    .filter(Traversal.returnAllButStartNode());
        }
    }
}
]]></programlisting>

        </example>
    </section>
</section>