/hazelcast-documentation/src/main/docbook/manual/content/executor/ExecutorService.xml

 1<?xml version='1.0' encoding='UTF-8'?>
 2
 3<!--
 4  ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved.
 5  ~
 6  ~ Licensed under the Apache License, Version 2.0 (the "License");
 7  ~ you may not use this file except in compliance with the License.
 8  ~ You may obtain a copy of the License at
 9  ~
10  ~ http://www.apache.org/licenses/LICENSE-2.0
11  ~
12  ~ Unless required by applicable law or agreed to in writing, software
13  ~ distributed under the License is distributed on an "AS IS" BASIS,
14  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  ~ See the License for the specific language governing permissions and
16  ~ limitations under the License.
17  -->
18
19<simplesect version='5.0' xmlns='http://docbook.org/ns/docbook'
20      xmlns:xi="http://www.w3.org/2001/XInclude"
21      xmlns:xlink="http://www.w3.org/1999/xlink"
22      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
23      xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
24      http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd">
25
26    <para>
27    One of the coolest features of Java 1.5 is the Executor framework, which allows you to asynchronously execute
28    your tasks, logical units of works, such as database query, complex calculation, image rendering etc. So one nice
29    way of executing such tasks would be running them asynchronously and doing other things meanwhile. When ready, get
30    the result and move on. If execution of the task takes longer than expected, you may consider canceling the task
31    execution. In Java Executor framework, tasks are implemented as
32    <literal>java.util.concurrent.Callable</literal> and <literal>java.util.Runnable</literal>.
33
34    <programlisting language="java"><![CDATA[import java.util.concurrent.Callable;
35import java.io.Serializable;
36
37public class Echo implements Callable<String>, Serializable {
38    String input = null;
39
40    public Echo() {
41    }
42
43    public Echo(String input) {
44        this.input = input;
45    }
46
47    public String call() {
48        return Hazelcast.getCluster().getLocalMember().toString() + ":" + input;
49    }
50}
51]]></programlisting>
52
53    Echo callable above, for instance, in its
54    <literal>call()</literal>
55    method, is returning the local member and the input passed in. Remember that
56    <literal>Hazelcast.getCluster().getLocalMember()</literal>
57    returns the local member and
58    <literal>toString()</literal>
59    returns the member's address
60    <literal>(ip + port)</literal>
61    in String form, just to see which member actually executed the code for our example. Of course, call() method can do
62    and return anything you like.
63
64    Executing a task by using executor framework is very straight forward. Simply obtain a
65    <literal>ExecutorService</literal>
66    instance, generally via
67    <literal>Executors</literal> and submit the task which returns a <literal>Future</literal>. After executing task, you don't have to wait for
68    execution to complete, you can process other things and when ready use the future object to retrieve the result as
69    show in code below.
70
71    <programlisting language="java"><![CDATA[ExecutorService executorService = Executors.newSingleThreadExecutor();
72Future<String> future = executorService.submit (new Echo("myinput"));
73//while it is executing, do some useful stuff
74//when ready, get the result of your execution
75String result = future.get();
76]]></programlisting>
77
78    If you need access to the current <literal>HazelcastInstance</literal> you are executing the task under, implement the interface <literal>HazelcastInstanceAware</literal>.
79    This will call the method <literal>setHazelcastInstance()</literal> prior to executing your task.
80        
81    </para>
82</simplesect>