= @Collection
: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 object collection.

== API

[source,java]
.Collection.java
----
@interface Collection {
  Class<? extends CollectionDomainEvent<?, ?>> domainEvent() default CollectionDomainEvent.Default.class;     // <.>
  Where hidden() default Where.NOT_SPECIFIED;     // <.>
  Class<?> typeOf() default // represents unspecified
void.class;     // <.>
}
----

<.> xref:#domainEvent[domainEvent]
+
--
Indicates that changes to the collection that 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:#hidden[hidden]
+
--
Indicates when the collection is not visible to the user.
--
<.> xref:#typeOf[typeOf]
+
--
The type-of the elements held within the collection.
--

== Members

[#domainEvent]
=== domainEvent

Indicates that changes to the collection that 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] .

Subscribers of this event can interact with the business rule checking (hide, disable, validate) and its modification (before and after).

For example:

----

public class Order {
  public static class OrderLineItems extends CollectionDomainEvent { ... }

  @CollectionInteraction(OrderLineItems.class)
  public SortedSet<OrderLine> getLineItems() { ...}
}
----

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

[#hidden]
=== hidden

Indicates when the collection is not visible to the user.

[#typeOf]
=== typeOf

The type-of the elements held within the collection.

This is only provided as a fallback; usually the framework can infer the element type of the collection from the collection method's generic type.

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

include::hooks/Collection_021_domainEvent.adoc[]

include::hooks/Collection_022_hidden.adoc[]

include::hooks/Collection_023_typeOf.adoc[]
