001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.commons.scxml.invoke; 018 019 import java.util.Map; 020 021 import org.apache.commons.scxml.SCInstance; 022 import org.apache.commons.scxml.TriggerEvent; 023 024 /** 025 * <p>The Invoker interface is used to define the possible interactions 026 * between the parent state machine (executor) and the types of invocable 027 * activities.</p> 028 * 029 * <p>Invocable activities must first register an Invoker implementation class 030 * for the appropriate "targettype" (attribute of <invoke>) with the 031 * parent <code>SCXMLExecutor</code>.</p> 032 * 033 * <p>The communication link between the parent state machine executor and 034 * the invoked activity is a bi-directional events pipe.</p> 035 * 036 * <p>All events triggered on the parent state machine get forwarded to the 037 * invoked activity. The processing semantics for these events depend 038 * upon the "targettype", and thereby vary per concrete implementation of 039 * this interface.</p> 040 * 041 * <p>The invoked activity in turn must fire a special "done" event 042 * when it concludes. It may fire additional events before the "done" 043 * event. The semantics of any additional events depend upon the 044 * "targettype". The invoked activity must not fire any events after the 045 * "done" event. The name of the special "done" event must be 046 * the ID of the parent state wherein the corresponding <invoke> 047 * resides, with the String ".invoke.done" appended.</p> 048 * 049 * <p>The Invoker "lifecycle" is outlined below: 050 * <ol> 051 * <li>Instantiation via {@link Class#newInstance()} 052 * (Invoker implementation requires accessible constructor).</li> 053 * <li>Configuration (setters for parent state ID and 054 * {@link SCInstance}).</li> 055 * <li>Initiation of invoked activity via invoke() method, passing 056 * the source URI and the map of params.</li> 057 * <li>Zero or more bi-directional event triggering.</li> 058 * <li>Either completion or cancellation.</li> 059 * </ol> 060 * </p> 061 * 062 * <p><b>Note:</b> The semantics of <invoke> are necessarily 063 * asynchronous, tending towards long(er) running interactions with external 064 * processes. Implementations must not communicate with the parent state 065 * machine executor in a synchronous manner. For synchronous 066 * communication semantics, use <event> or custom actions instead.</p> 067 */ 068 public interface Invoker { 069 070 /** 071 * Set the state ID of the owning state for the <invoke>. 072 * Implementations must use this ID for constructing the event name for 073 * the special "done" event (and optionally, for other event names 074 * as well). 075 * 076 * @param parentStateId The ID of the parent state. 077 */ 078 void setParentStateId(String parentStateId); 079 080 /** 081 * Set the "context" of the parent state machine, which provides the 082 * channel. 083 * 084 * @param scInstance The "context" of the parent state machine. 085 */ 086 void setSCInstance(SCInstance scInstance); 087 088 /** 089 * Begin this invocation. 090 * 091 * @param source The source URI of the activity being invoked. 092 * @param params The <param> values 093 * @throws InvokerException In case there is a fatal problem with 094 * invoking the source. 095 */ 096 void invoke(String source, Map params) 097 throws InvokerException; 098 099 /** 100 * Forwards the events triggered on the parent state machine 101 * on to the invoked activity. 102 * 103 * @param evts 104 * an array of external events which triggered during the last 105 * time quantum 106 * 107 * @throws InvokerException In case there is a fatal problem with 108 * processing the events forwarded by the 109 * parent state machine. 110 */ 111 void parentEvents(TriggerEvent[] evts) 112 throws InvokerException; 113 114 /** 115 * Cancel this invocation. 116 * 117 * @throws InvokerException In case there is a fatal problem with 118 * canceling this invoke. 119 */ 120 void cancel() 121 throws InvokerException; 122 123 } 124