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

Groups together all domain-specific metadata for an invokable action on a domain object or domain service.

== API

[source,java]
.Action.java
----
@interface Action {
  String choicesFrom() default "";     // <.>
  Class<? extends CommandDtoProcessor> commandDtoProcessor() default CommandDtoProcessor.class;     // <.>
  Publishing commandPublishing() default Publishing.NOT_SPECIFIED;     // <.>
  Class<? extends ActionDomainEvent<?>> domainEvent() default ActionDomainEvent.Default.class;     // <.>
  Publishing executionPublishing() default Publishing.NOT_SPECIFIED;     // <.>
  RestrictTo restrictTo() default RestrictTo.NOT_SPECIFIED;     // <.>
  SemanticsOf semantics() default SemanticsOf.NOT_SPECIFIED;     // <.>
  Class<?> typeOf() default // represents unspecified
void.class;     // <.>
  String fileAccept() default "";     // <.>
}
----

<.> xref:#choicesFrom[choicesFrom]
+
--
References a collection of a certain element type (by its member-id), for an action with scalar or collection parameters of that element type; the action's choices will be automatically populated from checkboxes rendered in the collection (multi-select).
--
<.> xref:#commandDtoProcessor[commandDtoProcessor]
+
--
The xref:refguide:applib:index/services/commanddto/processor/CommandDtoProcessor.adoc[CommandDtoProcessor] to process this command's DTO.
--
<.> xref:#commandPublishing[commandPublishing]
+
--
Whether action invocations, captured as xref:refguide:applib:index/services/command/Command.adoc[Command] s, should be published to xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] s.
--
<.> xref:#domainEvent[domainEvent]
+
--
Indicates that an invocation of the action should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService_ using a custom (subclass of) xref:refguide:applib:index/events/domain/ActionDomainEvent.adoc[ActionDomainEvent] .
--
<.> xref:#executionPublishing[executionPublishing]
+
--
Whether xref:refguide:applib:index/services/iactn/Execution.adoc[Execution] s (triggered by action invocations), should be published to xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] s.
--
<.> xref:#restrictTo[restrictTo]
+
--
Whether the action is restricted to prototyping, or whether it is available also in production mode.
--
<.> xref:#semantics[semantics]
+
--
The action semantics, either _SemanticsOf#SAFE_AND_REQUEST_CACHEABLE cached_ , _SemanticsOf#SAFE safe_ (query-only), _SemanticsOf#IDEMPOTENT idempotent_ or _SemanticsOf#NON_IDEMPOTENT non-idempotent_ .
--
<.> xref:#typeOf[typeOf]
+
--
If the action returns a collection, then this hints as to the run-time type of the objects within that collection.
--
<.> xref:#fileAccept[fileAccept]
+
--
For downloading xref:refguide:applib:index/value/Blob.adoc[Blob] or xref:refguide:applib:index/value/Clob.adoc[Clob] , optionally restrict the files accepted (eg `.xslx` ).
--

== Members

[#choicesFrom]
=== choicesFrom

References a collection of a certain element type (by its member-id), for an action with scalar or collection parameters of that element type; the action's choices will be automatically populated from checkboxes rendered in the collection (multi-select).

This will also result in the action being rendered near to the collection, similar to the way in which _ActionLayout#associateWith()_ does.

If there are multiple actions associated with a collection, either by way of _Action#choicesFrom()_ or using _ActionLayout#associateWith()_ , then their order in the UI can be influenced using _ActionLayout#sequence()_ .

[#commandDtoProcessor]
=== commandDtoProcessor

The xref:refguide:applib:index/services/commanddto/processor/CommandDtoProcessor.adoc[CommandDtoProcessor] to process this command's DTO.

The processor itself is used by xref:refguide:applib:index/services/commanddto/conmap/ContentMappingServiceForCommandDto.adoc[ContentMappingServiceForCommandDto] and xref:refguide:applib:index/services/commanddto/conmap/ContentMappingServiceForCommandsDto.adoc[ContentMappingServiceForCommandsDto] to dynamically transform the DTOs.

[#commandPublishing]
=== commandPublishing

Whether action invocations, captured as xref:refguide:applib:index/services/command/Command.adoc[Command] s, should be published to xref:refguide:applib:index/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] s.

[#domainEvent]
=== domainEvent

Indicates that an invocation of the action should be posted to the _org.apache.causeway.applib.services.eventbus.EventBusService_ using a custom (subclass of) xref:refguide:applib:index/events/domain/ActionDomainEvent.adoc[ActionDomainEvent] .

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

For example:

----
public class SomeObject{
    public static class ChangeStartDateDomainEvent extends ActionDomainEvent<SomeObject> { ... }

    @Action(domainEvent=ChangedStartDateDomainEvent.class)
    public void changeStartDate(final Date startDate) { ...}
    ...
}
----

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

[#executionPublishing]
=== executionPublishing

Whether xref:refguide:applib:index/services/iactn/Execution.adoc[Execution] s (triggered by action invocations), should be published to xref:refguide:applib:index/services/publishing/spi/ExecutionSubscriber.adoc[ExecutionSubscriber] s.

[#restrictTo]
=== restrictTo

Whether the action is restricted to prototyping, or whether it is available also in production mode.

By default there are no restrictions, with the action being available in all environments.

[#semantics]
=== semantics

The action semantics, either _SemanticsOf#SAFE_AND_REQUEST_CACHEABLE cached_ , _SemanticsOf#SAFE safe_ (query-only), _SemanticsOf#IDEMPOTENT idempotent_ or _SemanticsOf#NON_IDEMPOTENT non-idempotent_ .

The action's semantics determine whether objects are modified as the result of invoking this action (if not, the results can be cached for the remainder of the request). If the objects do cause a change in state, they additionally determine whether re-invoking the action would result in a further change.

There are also `...ARE_YOU_SURE` variants (@link _SemanticsOf#IDEMPOTENT_ARE_YOU_SURE_ and (@link _SemanticsOf#NON_IDEMPOTENT_ARE_YOU_SURE_ that cause a confirmation dialog to be displayed in the Wicket viewer.

[#typeOf]
=== typeOf

If the action returns a collection, then this hints as to the run-time type of the objects within that collection.

This is only provided as a fallback; usually the framework can infer the element type of the collection from the action method's return type (eg if it returns `Collection` instead of `Collection<Customer>` )

[#fileAccept]
=== fileAccept

For downloading xref:refguide:applib:index/value/Blob.adoc[Blob] or xref:refguide:applib:index/value/Clob.adoc[Clob] , optionally restrict the files accepted (eg `.xslx` ).

The value should be of the form "file_extension|audio/*|video/*|image/*|media_type".

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

include::hooks/Action_021-associating.adoc[]

include::hooks/Action_022-action-semantics.adoc[]

include::hooks/Action_023-deployment-modes.adoc[]

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

include::hooks/Action_025-execution-publishing.adoc[]

include::hooks/Action_026-command-processing.adoc[]

include::hooks/Action_027-collection-types.adoc[]

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