=== Nature

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:

The xref:refguide:applib:index/annotation/DomainObject.adoc#nature[nature()] element is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer).
If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.

For example:

[source,java]
----
@DomainObject(nature=Nature.VIEW_MODEL)
public class PieChartAnalysis {
    ...
}
----

Specifically, the nature must be one of:

* `NOT_SPECIFIED,`
+
(the default); specifies no paricular semantics for the domain class.

* `ENTITY`
+
indicates that the domain object is an entity whose persistence is managed internally by Apache Causeway, using the JDO/DataNucleus objectstore.

* `MIXIN`
+
indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
+
For further discussion on using mixins, see xref:userguide:ROOT:overview.adoc[mixins] in the user guide.

* `VIEW_MODEL`
+
indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.

** _Variant: External Entity_
+
Or indicates that the domain object is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system.
For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP.
+
The identity of an external entity is determined solely by the state of entity's properties.
The framework will automatically recreate the domain object each time it is interacted with.

** _Variant: In-Memory Entity_
+
Or indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure.
+
The identity of an in-memory entity is determined solely by the state of entity's properties.
The framework will automatically recreate the domain object each time it is interacted with.


Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.

[NOTE]
====
For `VIEW_MODEL` domain objects the state of the object is encoded into its internal OID (represented ultimately as its URL), and is recreated directly from that URL.

Because this particular implementation was originally added to Apache Causeway in support of view models, the term was also used for the logically different external entities and in-memory entities.

The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
====

[NOTE]
====
On the other hand, view models defined in this way do have some limitations; see xref:refguide:applib:index/annotation/DomainObject.adoc#view-models[View Models] for further discussion.

These limitations do _not_ apply to xref:userguide:ROOT:view-models.adoc#jaxb[JAXB] view models.
If you are using view models heavily, you may wish to restrict yourself to just the JAXB flavour.
====


