<?xml version='1.0' encoding='UTF-8'?>

<!--
  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
  ~
  ~ Licensed 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.
  -->

<simplesect version='5.0' xmlns='http://docbook.org/ns/docbook'
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
      http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">

    <para>
    One of the coolest features of Java 1.5 is the Executor framework, which allows you to asynchronously execute
    your tasks, logical units of works, such as database query, complex calculation, image rendering etc. So one nice
    way of executing such tasks would be running them asynchronously and doing other things meanwhile. When ready, get
    the result and move on. If execution of the task takes longer than expected, you may consider canceling the task
    execution. In Java Executor framework, tasks are implemented as
    <literal>java.util.concurrent.Callable</literal> and <literal>java.util.Runnable</literal>.

    <programlisting language="java"><![CDATA[import java.util.concurrent.Callable;
import java.io.Serializable;

public class Echo implements Callable<String>, Serializable {
    String input = null;

    public Echo() {
    }

    public Echo(String input) {
        this.input = input;
    }

    public String call() {
        return Hazelcast.getCluster().getLocalMember().toString() + ":" + input;
    }
}
]]></programlisting>

    Echo callable above, for instance, in its
    <literal>call()</literal>
    method, is returning the local member and the input passed in. Remember that
    <literal>Hazelcast.getCluster().getLocalMember()</literal>
    returns the local member and
    <literal>toString()</literal>
    returns the member's address
    <literal>(ip + port)</literal>
    in String form, just to see which member actually executed the code for our example. Of course, call() method can do
    and return anything you like.

    Executing a task by using executor framework is very straight forward. Simply obtain a
    <literal>ExecutorService</literal>
    instance, generally via
    <literal>Executors</literal> and submit the task which returns a <literal>Future</literal>. After executing task, you don't have to wait for
    execution to complete, you can process other things and when ready use the future object to retrieve the result as
    show in code below.

    <programlisting language="java"><![CDATA[ExecutorService executorService = Executors.newSingleThreadExecutor();
Future<String> future = executorService.submit (new Echo("myinput"));
//while it is executing, do some useful stuff
//when ready, get the result of your execution
String result = future.get();
]]></programlisting>

    If you need access to the current <literal>HazelcastInstance</literal> you are executing the task under, implement the interface <literal>HazelcastInstanceAware</literal>.
    This will call the method <literal>setHazelcastInstance()</literal> prior to executing your task.
        
    </para>
</simplesect>