<h2>How to implement scheduled events<aclass="headerlink"href="#how-to-implement-scheduled-events"title="Permalink to this headline">¶</a></h2>
<p>There are two main steps to implementing scheduled events:</p>
<ulclass="simple">
<li>Have your <codeclass="docutils literal"><spanclass="pre">ContractState</span></code> implementation also implement <codeclass="docutils literal"><spanclass="pre">SchedulableState</span></code>. This requires a method named
<codeclass="docutils literal"><spanclass="pre">nextScheduledActivity</span></code> to be implemented which returns an optional <codeclass="docutils literal"><spanclass="pre">ScheduledActivity</span></code> instance.
<codeclass="docutils literal"><spanclass="pre">ScheduledActivity</span></code> captures what <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> instance each node will run, to perform the activity, and when it
will run is described by a <codeclass="docutils literal"><spanclass="pre">java.time.Instant</span></code>. Once your state implements this interface and is tracked by the
wallet, it can expect to be queried for the next activity when recorded via the <codeclass="docutils literal"><spanclass="pre">ServiceHub.recordTransactions</span></code>
method during protocols execution.</li>
<li>If nothing suitable exists, implement a <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> to be executed by each node as the activity itself.
The important thing to remember is that each node that is party to the transaction, in the current implementation,
will execute the same <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> so that needs to establish roles in the business process based on the contract
state and the node it is running on, and follow different but complementary paths through the business logic.</li>
</ul>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">The scheduler’s clock always operates in the UTC time zone for uniformity, so any time zone logic must be
performed by the contract, using <codeclass="docutils literal"><spanclass="pre">ZonedDateTime</span></code>.</p>
</div>
<p>In the short term, until we have automatic protocol session set up, you will also likely need to install a network
handler to help with obtaining a unqiue and secure random session. An example is described below.</p>
<p>The production and consumption of <codeclass="docutils literal"><spanclass="pre">ContractStates</span></code> is observed by the scheduler and the activities associated with
any consumed states are unscheduled. Any newly produced states are then queried via the <codeclass="docutils literal"><spanclass="pre">nextScheduledActivity</span></code>
method and if they do not return <codeclass="docutils literal"><spanclass="pre">null</span></code> then that activity is scheduled based on the content of the
<h2>An example<aclass="headerlink"href="#an-example"title="Permalink to this headline">¶</a></h2>
<p>Let’s take an example of the Interest Rate Swap fixings for our scheduled events. The first task is to implement the
<codeclass="docutils literal"><spanclass="pre">nextScheduledActivity</span></code> method on the <codeclass="docutils literal"><spanclass="pre">State</span></code>.</p>
<divclass="codeset container">
<divclass="highlight-kotlin"><divclass="highlight"><pre><span></span>override fun nextScheduledActivity(thisStateRef: StateRef,
<p>The first thing this does is establish if there are any remaining fixings. If there are none, then it returns <codeclass="docutils literal"><spanclass="pre">null</span></code>
to indicate that there is no activity to schedule. Otherwise it calculates the <codeclass="docutils literal"><spanclass="pre">Instant</span></code> at which the interest rate
should become available and schedules an activity at that time to work out what roles each node will take in the fixing
business process and to take on those roles. That <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> will be handed the <codeclass="docutils literal"><spanclass="pre">StateRef</span></code> for the interest
rate swap <codeclass="docutils literal"><spanclass="pre">State</span></code> in question, as well as a tolerance <codeclass="docutils literal"><spanclass="pre">Duration</span></code> of how long to wait after the activity is triggered
for the interest rate before indicating an error.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">The use of the factory to create a <codeclass="docutils literal"><spanclass="pre">ProtocolLogicRef</span></code> instance to embed in the <codeclass="docutils literal"><spanclass="pre">ScheduledActivity</span></code>. This is a
way to create a reference to the <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> class and it’s constructor parameters to instantiate that can be
checked against a per node whitelist of approved and allowable types as part of our overall security sandboxing.</p>
</div>
<p>As previously mentioned, we currently need a small network handler to assist with session setup until the work to
automate that is complete. See the interest rate swap specific implementation <codeclass="docutils literal"><spanclass="pre">FixingSessionInitiationHandler</span></code> which
is responsible for starting a <codeclass="docutils literal"><spanclass="pre">ProtocolLogic</span></code> to perform one role in the fixing protocol with the <codeclass="docutils literal"><spanclass="pre">sessionID</span></code> sent
by the <codeclass="docutils literal"><spanclass="pre">FixingRoleDecider</span></code> on the other node which then launches the other role in the fixing protocol. Currently
the handler needs to be manually installed in the node.</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
