= @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] ).

== 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 "Disabled";     // <.>
  Publishing entityChangePublishing() default Publishing.NOT_SPECIFIED;     // <.>
  Introspection introspection() default Introspection.NOT_SPECIFIED;     // <.>
  String mixinMethod() default "$$";     // <.>
  Nature nature() default Nature.NOT_SPECIFIED;     // <.>
  @Deprecated(forRemoval = true, since = "2.0.0-M8")
String logicalTypeName() default "";     // <.>
  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;     // <.>
}
----

<.> 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.isis.applib.services.publishing.spi.EntityPropertyChangeSubscriber_ s and whether entity changes, captured as _org.apache.isis.applib.services.publishing.spi.EntityChanges_ , should be published to _org.apache.isis.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:#logicalTypeName[logicalTypeName]
+
--
[WARNING]
====
[red]#_deprecated:_#

use _Named_ instead
====

The logical name of this object's type, that uniquely and fully qualifies it. The logical name is analogous to - but independent of - the actual fully qualified class name. eg. _sales.Customer_ for a class 'org.mycompany.dom.Customer'
--
<.> xref:#createdLifecycleEvent[createdLifecycleEvent]
+
--
Indicates that the loading of the domain object should be posted to the _org.apache.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:refguide:applib:index/events/domain/CollectionDomainEvent.adoc[CollectionDomainEvent] .
--

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

[#entityChangePublishing]
=== entityChangePublishing

Whether entity changes (persistent property updates) should be published to _org.apache.isis.applib.services.publishing.spi.EntityPropertyChangeSubscriber_ s and whether entity changes, captured as _org.apache.isis.applib.services.publishing.spi.EntityChanges_ , should be published to _org.apache.isis.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 `$$`.

[#nature]
=== nature

The nature of this domain object.

[#logicalTypeName]
=== logicalTypeName

[WARNING]
====
[red]#_deprecated:_#

use _Named_ instead
====

The logical name of this object's type, that uniquely and fully qualifies it. The logical name is analogous to - but independent of - the actual fully qualified class name. eg. _sales.Customer_ for a class 'org.mycompany.dom.Customer'

This value, if specified, is used in the serialized form of the object's xref:refguide:applib:index/services/bookmark/Bookmark.adoc[Bookmark] . A xref:refguide:applib:index/services/bookmark/Bookmark.adoc[Bookmark] is used by the framework to uniquely identify an object over time (same concept as a URN). Otherwise, if not specified, the fully qualified class name is used instead.

[#createdLifecycleEvent]
=== createdLifecycleEvent

Indicates that the loading of the domain object should be posted to the _org.apache.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.isis.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.

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[]
