= @DomainObject
: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.

Domain semantics for domain objects (entities and view models; for services see xref:refguide:applib:index/annotation/DomainService.adoc[DomainService] ).

If - for the currently logged on user - none of the domain object's members are effectively visible, (or if there are no members to begin with), the object instance is considered hidden. Hence a NOT-AUTHORIZED page will be displayed instead.

== API

[source,java]
.DomainObject.java
----
@interface DomainObject {
  String[] aliased() default {};     // <.>
  Class<?> autoCompleteRepository() default Object.class;     // <.>
  String autoCompleteMethod() default "autoComplete";     // <.>
  Bounding bounding() default Bounding.NOT_SPECIFIED;     // <.>
  Editing editing() default Editing.NOT_SPECIFIED;     // <.>
  String editingDisabledReason() default "";     // <.>
  Publishing entityChangePublishing() default Publishing.NOT_SPECIFIED;     // <.>
  Introspection introspection() default Introspection.NOT_SPECIFIED;     // <.>
  String mixinMethod() default "$$";     // <.>
  Nature nature() default Nature.NOT_SPECIFIED;     // <.>
  Class<? extends ObjectCreatedEvent<?>> createdLifecycleEvent() default ObjectCreatedEvent.Default.class;     // <.>
  Class<? extends ObjectPersistingEvent<?>> persistingLifecycleEvent() default ObjectPersistingEvent.Default.class;     // <.>
  Class<? extends ObjectPersistedEvent<?>> persistedLifecycleEvent() default ObjectPersistedEvent.Default.class;     // <.>
  Class<? extends ObjectLoadedEvent<?>> loadedLifecycleEvent() default ObjectLoadedEvent.Default.class;     // <.>
  Class<? extends ObjectUpdatingEvent<?>> updatingLifecycleEvent() default ObjectUpdatingEvent.Default.class;     // <.>
  Class<? extends ObjectUpdatedEvent<?>> updatedLifecycleEvent() default ObjectUpdatedEvent.Default.class;     // <.>
  Class<? extends ObjectRemovingEvent<?>> removingLifecycleEvent() default ObjectRemovingEvent.Default.class;     // <.>
  Class<? extends ActionDomainEvent<?>> actionDomainEvent() default ActionDomainEvent.Default.class;     // <.>
  Class<? extends PropertyDomainEvent<?, ?>> propertyDomainEvent() default PropertyDomainEvent.Default.class;     // <.>
  Class<? extends CollectionDomainEvent<?, ?>> collectionDomainEvent() default CollectionDomainEvent.Default.class;     // <.>
  int queryDslAutoCompleteMinLength() default QueryDslAutoCompleteConstants.MIN_LENGTH;     // <.>
  int queryDslAutoCompleteLimitResults() default QueryDslAutoCompleteConstants.LIMIT_RESULTS;     // <.>
  Class<?> queryDslAutoCompleteAdditionalPredicateRepository() default Object.class;     // <.>
  String queryDslAutoCompleteAdditionalPredicateMethod() default QueryDslAutoCompleteConstants.ADDITIONAL_PREDICATE_METHOD_NAME;     // <.>
}
----

<.> xref:#aliased[aliased]
+
--
Alternative logical type name(s) for the annotated type.
--
<.> xref:#autoCompleteRepository[autoCompleteRepository]
+
--
The class of the domain service that provides an `autoComplete(String)` method.
--
<.> xref:#autoCompleteMethod[autoCompleteMethod]
+
--
The method to use in order to perform the auto-complete search (defaults to "autoComplete").
--
<.> xref:#bounding[bounding]
+
--
Indicates that the class has a bounded, or finite, set of instances.
--
<.> xref:#editing[editing]
+
--
Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.
--
<.> xref:#editingDisabledReason[editingDisabledReason]
+
--
If _#editing()_ is set to _Editing#DISABLED_ , then the reason to provide to the user as to why the object's properties cannot be edited/collections modified.
--
<.> xref:#entityChangePublishing[entityChangePublishing]
+
--
Whether entity changes (persistent property updates) should be published to _org.apache.causeway.applib.services.publishing.spi.EntityPropertyChangeSubscriber_ s and whether entity changes, captured as _org.apache.causeway.applib.services.publishing.spi.EntityChanges_ , should be published to _org.apache.causeway.applib.services.publishing.spi.EntityChangesSubscriber_ s.
--
<.> xref:#introspection[introspection]
+
--
Controls on a per class basis, how meta-model class introspection should process members, supporting methods and callback methods.
--
<.> xref:#mixinMethod[mixinMethod]
+
--
Applicable only if _#nature()_ is _Nature#MIXIN_ , indicates the name of the method within the mixin class to be inferred as the action of that mixin.
--
<.> xref:#nature[nature]
+
--
The nature of this domain object.
--
<.> xref:#createdLifecycleEvent[createdLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectCreatedEvent.adoc[ObjectCreatedEvent] .
--
<.> xref:#persistingLifecycleEvent[persistingLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectPersistingEvent.adoc[ObjectPersistingEvent] .
--
<.> xref:#persistedLifecycleEvent[persistedLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectPersistedEvent.adoc[ObjectPersistedEvent] .
--
<.> xref:#loadedLifecycleEvent[loadedLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectLoadedEvent.adoc[ObjectLoadedEvent] .
--
<.> xref:#updatingLifecycleEvent[updatingLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectUpdatingEvent.adoc[ObjectUpdatingEvent] .
--
<.> xref:#updatedLifecycleEvent[updatedLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectUpdatedEvent.adoc[ObjectUpdatedEvent] .
--
<.> xref:#removingLifecycleEvent[removingLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectRemovingEvent.adoc[ObjectRemovingEvent] .
--
<.> xref:#actionDomainEvent[actionDomainEvent]
+
--
Indicates that an invocation of _any_ action of the domain object (that do not themselves specify their own `@Action(domainEvent=...)` should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using the specified custom (subclass of) xref:refguide:applib:index/events/domain/ActionDomainEvent.adoc[ActionDomainEvent] .
--
<.> xref:#propertyDomainEvent[propertyDomainEvent]
+
--
Indicates that changes to _any_ property of the domain object (that do not themselves specify their own `@Property(domainEvent=...)` should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using the specified custom (subclass of) xref:refguide:applib:index/events/domain/PropertyDomainEvent.adoc[PropertyDomainEvent] .
--
<.> xref:#collectionDomainEvent[collectionDomainEvent]
+
--
Indicates that changes to _any_ collection of the domain object (that do not themselves specify their own `@Collection(domainEvent=...)` should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/domain/CollectionDomainEvent.adoc[CollectionDomainEvent] .
--
<.> xref:#queryDslAutoCompleteMinLength[queryDslAutoCompleteMinLength]
+
--
If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute determines the minimum number of characters that must be entered before the query is submitted. Fine-tunes how auto-complete queries work, Whether to use the value of this (string) property for auto.
--
<.> xref:#queryDslAutoCompleteLimitResults[queryDslAutoCompleteLimitResults]
+
--
If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute can be used to limit the number of rows that are returned.
--
<.> xref:#queryDslAutoCompleteAdditionalPredicateRepository[queryDslAutoCompleteAdditionalPredicateRepository]
+
--
If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute can be used to specify additional predicate(s) to always be added to the autocomplete (for example to search only for current or active objects).
--
<.> xref:#queryDslAutoCompleteAdditionalPredicateMethod[queryDslAutoCompleteAdditionalPredicateMethod]
+
--
If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute can be used to specify the name of a method in a repository to provide additional predicate(s) to always be added to the autocomplete (for example to search only for current or active objects).
--

== Members

[#aliased]
=== aliased

Alternative logical type name(s) for the annotated type.

[#autoCompleteRepository]
=== autoCompleteRepository

The class of the domain service that provides an `autoComplete(String)` method.

It is sufficient to specify an interface rather than a concrete type.

[#autoCompleteMethod]
=== autoCompleteMethod

The method to use in order to perform the auto-complete search (defaults to "autoComplete").

The method is required to accept a single string parameter, and must return a list of the domain type.

[#bounding]
=== bounding

Indicates that the class has a bounded, or finite, set of instances.

Takes precedence over auto-complete.

Note: this replaces bounded=true|false prior to v2.x

[#editing]
=== editing

Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.

Note that non-editable objects can nevertheless have actions invoked upon them.

[#editingDisabledReason]
=== editingDisabledReason

If _#editing()_ is set to _Editing#DISABLED_ , then the reason to provide to the user as to why the object's properties cannot be edited/collections modified.

If left empty (default), no reason is given.

[#entityChangePublishing]
=== entityChangePublishing

Whether entity changes (persistent property updates) should be published to _org.apache.causeway.applib.services.publishing.spi.EntityPropertyChangeSubscriber_ s and whether entity changes, captured as _org.apache.causeway.applib.services.publishing.spi.EntityChanges_ , should be published to _org.apache.causeway.applib.services.publishing.spi.EntityChangesSubscriber_ s.

[#introspection]
=== introspection

Controls on a per class basis, how meta-model class introspection should process members, supporting methods and callback methods.

[#mixinMethod]
=== mixinMethod

Applicable only if _#nature()_ is _Nature#MIXIN_ , indicates the name of the method within the mixin class to be inferred as the action of that mixin.

Supporting methods are then derived from that method name. For example, if the mixin method name is "act", then the _disable_ supporting method will be "disableAct".

Typical examples are "act", "prop", "coll", "exec", "execute", "invoke", "apply" and so on. The default name is `$$`.

 *NOTE* : it's more typical to instead use xref:refguide:applib:index/annotation/Action.adoc[Action] , xref:refguide:applib:index/annotation/Property.adoc[Property] or xref:refguide:applib:index/annotation/Collection.adoc[Collection] as the class-level annotation, indicating that the domain object is a mixin. The mixin method name for these is, respectively, "act", "prop" and "coll".

[#nature]
=== nature

The nature of this domain object.

Most common are natures of _Nature#ENTITY_ and _Nature#VIEW_MODEL_ . For mixins, rather than use a nature of _Nature#MIXIN_ , it's more typical to instead use xref:refguide:applib:index/annotation/Action.adoc[Action] , xref:refguide:applib:index/annotation/Property.adoc[Property] or xref:refguide:applib:index/annotation/Collection.adoc[Collection] as the class-level annotation, indicating that the domain object is a mixin. The _#mixinMethod() mixin method name_ for these is, respectively, "act", "prop" and "coll".

The _Nature#BEAN_ nature is for internally use, and should not normally be specified explicitly.

[#createdLifecycleEvent]
=== createdLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectCreatedEvent.adoc[ObjectCreatedEvent] .

This subclass must provide a no-arg constructor; the fields are set reflectively.

[#persistingLifecycleEvent]
=== persistingLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectPersistingEvent.adoc[ObjectPersistingEvent] .

This subclass must provide a no-arg constructor; the fields are set reflectively.

[#persistedLifecycleEvent]
=== persistedLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectPersistedEvent.adoc[ObjectPersistedEvent] .

This subclass must provide a no-arg constructor; the fields are set reflectively.

[#loadedLifecycleEvent]
=== loadedLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectLoadedEvent.adoc[ObjectLoadedEvent] .

This subclass must provide a no-arg constructor; the fields are set reflectively.

[#updatingLifecycleEvent]
=== updatingLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectUpdatingEvent.adoc[ObjectUpdatingEvent] .

This subclass must provide a no-arg constructor; the fields are set reflectively.

[#updatedLifecycleEvent]
=== updatedLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectUpdatedEvent.adoc[ObjectUpdatedEvent] .

This subclass must provide a no-arg constructor; the fields are set reflectively.

[#removingLifecycleEvent]
=== removingLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/lifecycle/ObjectRemovingEvent.adoc[ObjectRemovingEvent] .

This subclass must provide a no-arg constructor; the fields are set reflectively.

[#actionDomainEvent]
=== actionDomainEvent

Indicates that an invocation of _any_ action of the domain object (that do not themselves specify their own `@Action(domainEvent=...)` should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using the specified custom (subclass of) xref:refguide:applib:index/events/domain/ActionDomainEvent.adoc[ActionDomainEvent] .

For example:

----
@DomainObject(actionDomainEvent=SomeObject.GenericActionDomainEvent.class)
public class SomeObject{
    public static class GenericActionDomainEvent extends ActionDomainEvent<Object> { ... }

    public void changeStartDate(final Date startDate) { ...}
    ...
}
----

This will result in all actions as a more specific type to use) to emit this event.

This subclass must provide a no-arg constructor; the fields are set reflectively. It must also use `Object` as its generic type. This is to allow mixins to also emit the same event.

[#propertyDomainEvent]
=== propertyDomainEvent

Indicates that changes to _any_ property of the domain object (that do not themselves specify their own `@Property(domainEvent=...)` should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using the specified custom (subclass of) xref:refguide:applib:index/events/domain/PropertyDomainEvent.adoc[PropertyDomainEvent] .

For example:

----
@DomainObject(propertyDomainEvent=SomeObject.GenericPropertyDomainEvent.class)
public class SomeObject{

   public LocalDate getStartDate() { ...}
}
----

This subclass must provide a no-arg constructor; the fields are set reflectively. It must also use `Object` as its generic type. This is to allow mixins to also emit the same event.

[#collectionDomainEvent]
=== collectionDomainEvent

Indicates that changes to _any_ collection of the domain object (that do not themselves specify their own `@Collection(domainEvent=...)` should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/domain/CollectionDomainEvent.adoc[CollectionDomainEvent] .

For example:

----
@DomainObject(collectionDomainEvent=Order.GenericCollectionDomainEvent.class)
public class Order {

  public SortedSet<OrderLine> getLineItems() { ...}
}
----

This subclass must provide a no-arg constructor; the fields are set reflectively. It must also use `Object` as its generic type. This is to allow mixins to also emit the same event.

[#queryDslAutoCompleteMinLength]
=== queryDslAutoCompleteMinLength

If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute determines the minimum number of characters that must be entered before the query is submitted. Fine-tunes how auto-complete queries work, Whether to use the value of this (string) property for auto.

NOTE: this feature requires that the `querydsl-xxx` module (for JDO or JPA as required) is included as part of the application manifest. Otherwise, no autocomplete will be generated.

NOTE: if _DomainObject#autoCompleteRepository()_ (and _DomainObject#autoCompleteMethod()_ ) have been specified, then these take precedence of the query DSL auto-complete.

[#queryDslAutoCompleteLimitResults]
=== queryDslAutoCompleteLimitResults

If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute can be used to limit the number of rows that are returned.

NOTE: if _DomainObject#autoCompleteRepository()_ (and _DomainObject#autoCompleteMethod()_ ) have been specified, then these take precedence of the query DSL auto-complete.

NOTE: this feature requires that the `querydsl-xxx` module (for JDO or JPA as required) is included as part of the application manifest. Otherwise, no autocomplete will be generated.

[#queryDslAutoCompleteAdditionalPredicateRepository]
=== queryDslAutoCompleteAdditionalPredicateRepository

If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute can be used to specify additional predicate(s) to always be added to the autocomplete (for example to search only for current or active objects).

If this attribute is specified, it indicates the class of a repository service that includes a method which returns an additional predicate to be applied. The default name of that method is "queryDslAutoCompleteAdditionalPredicates" (but can be overridden if required using _DomainObject#queryDslAutoCompleteAdditionalPredicateMethod()_ ).

NOTE: this feature requires that the `querydsl-xxx` module (for JDO or JPA as required) is included as part of the application manifest. Otherwise, no autocomplete will be generated.

[#queryDslAutoCompleteAdditionalPredicateMethod]
=== queryDslAutoCompleteAdditionalPredicateMethod

If at least one property of the entity has been annotated with _Property#queryDslAutoComplete()_ , then that property (and any others) will automatically be used for autocomplete functionality; this attribute can be used to specify the name of a method in a repository to provide additional predicate(s) to always be added to the autocomplete (for example to search only for current or active objects).

NOTE: this feature requires that the `querydsl-xxx` module (for JDO or JPA as required) is included as part of the application manifest. Otherwise, no autocomplete will be generated.

include::hooks/DomainObject_010-examples-and-usage.adoc[]

include::hooks/DomainObject_021-logicalTypeName.adoc[]

include::hooks/DomainObject_022-nature.adoc[]

include::hooks/DomainObject_023-editing.adoc[]

include::hooks/DomainObject_024-domain-events.adoc[]

include::hooks/DomainObject_025-lifecycle-events.adoc[]

include::hooks/DomainObject_026-entityChangePublishing.adoc[]

include::hooks/DomainObject_027-bounding.adoc[]

include::hooks/DomainObject_028-autoCompleteRepository.adoc[]

include::hooks/DomainObject_029-mixinMethod.adoc[]

include::hooks/DomainObject_040-see-also.adoc[]
