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

Represents an action invocation or property modification, resulting in some state change of the system. It captures not only the target object and arguments passed, but also builds up the call-graph, and captures metrics, eg for profiling.

The `Interaction` can be used to obtain the xref:refguide:applib:index/services/command/Command.adoc[Command] object representing the top-level invocation action/property edit.

The distinction between xref:refguide:applib:index/services/command/Command.adoc[Command] and this object is perhaps subtle: the former represents the intention to invoke an action/edit a property, whereas this represents the actual invocation/edit itself.

To confuse matters slightly, historically the xref:refguide:applib:index/services/command/Command.adoc[Command] interface defines members (specifically: _Command#getStartedAt()_ , _Command#getCompletedAt()_ , _Command#getResult()_ , _Command#getException()_ ) which logically belong to this class instead; they remain in xref:refguide:applib:index/services/command/Command.adoc[Command] for backward compatibility only (and have been deprecated).

== API

[source,java]
.Interaction.java
----
interface Interaction {
  UUID getInteractionId()     // <.>
  Command getCommand()     // <.>
  Execution<?, ?> getCurrentExecution()     // <.>
  Execution<?, ?> getPriorExecution()     // <.>
}
----

<.> xref:#getInteractionId_[getInteractionId()]
+
--
The unique identifier of this interaction (inherited from xref:refguide:applib:index/mixins/system/HasInteractionId.adoc[HasInteractionId] )
--
<.> xref:#getCommand_[getCommand()]
+
--
Represents the _intention_ to perform this interaction.
--
<.> xref:#getCurrentExecution_[getCurrentExecution()]
+
--
The current (most recently pushed) xref:refguide:applib:index/services/iactn/Execution.adoc[Execution] .
--
<.> xref:#getPriorExecution_[getPriorExecution()]
+
--
The execution that preceded the current one.
--

== Members

[#getInteractionId_]
=== getInteractionId()

The unique identifier of this interaction (inherited from xref:refguide:applib:index/mixins/system/HasInteractionId.adoc[HasInteractionId] )

This can be used to correlate audit records and transactions happening as a consequence or within the interaction.

[#getCommand_]
=== getCommand()

Represents the _intention_ to perform this interaction.

[#getCurrentExecution_]
=== getCurrentExecution()

The current (most recently pushed) xref:refguide:applib:index/services/iactn/Execution.adoc[Execution] .

[#getPriorExecution_]
=== getPriorExecution()

The execution that preceded the current one.

include::hooks/Interaction_010-implementation.adoc[]

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