| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc --> |
| <title>org.apache.geode.cache.execute (Apache Geode 1.15.0)</title> |
| <link rel="stylesheet" type="text/css" href="../../../../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../../../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="org.apache.geode.cache.execute (Apache Geode 1.15.0)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/geode/cache/control/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/geode/cache/lucene/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/geode/cache/execute/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package org.apache.geode.cache.execute</h1> |
| <div class="docSummary"> |
| <div class="block"> |
| The <code>org.apache.geode.cache.execute</code> package provides APIs used |
| for function execution on gemfire system members.</div> |
| </div> |
| <p>See: <a href="#package.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> |
| <caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Interface</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/Execution.html" title="interface in org.apache.geode.cache.execute">Execution</a><IN,OUT,AGG></td> |
| <td class="colLast"> |
| <div class="block">Provides methods to build the context for the execution of a <a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute"><code>Function</code></a> .</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute">Function</a><T></td> |
| <td class="colLast"> |
| <div class="block">Defines the interface a user defined function implements.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/FunctionContext.html" title="interface in org.apache.geode.cache.execute">FunctionContext</a><T1></td> |
| <td class="colLast"> |
| <div class="block">Defines the execution context of a <a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute"><code>Function</code></a>.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/RegionFunctionContext.html" title="interface in org.apache.geode.cache.execute">RegionFunctionContext</a></td> |
| <td class="colLast"> |
| <div class="block">Defines the execution context of a data dependent <a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute"><code>Function</code></a>.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/ResultCollector.html" title="interface in org.apache.geode.cache.execute">ResultCollector</a><T,S></td> |
| <td class="colLast"> |
| <div class="block"> |
| Defines the interface for a container that gathers results from function execution.<br> |
| GemFire provides a default implementation for ResultCollector.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/ResultSender.html" title="interface in org.apache.geode.cache.execute">ResultSender</a><T></td> |
| <td class="colLast"> |
| <div class="block">Provides methods to send results back to the ResultCollector.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/FunctionAdapter.html" title="class in org.apache.geode.cache.execute">FunctionAdapter</a></td> |
| <td class="colLast">Deprecated |
| <div class="block"><span class="deprecationComment">Use <a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute"><code>Function</code></a> instead.</span></div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/FunctionService.html" title="class in org.apache.geode.cache.execute">FunctionService</a></td> |
| <td class="colLast"> |
| <div class="block">Provides the entry point into execution of user defined <a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute">Function</a>s.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation"> |
| <caption><span>Exception Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Exception</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/EmptyRegionFunctionException.html" title="class in org.apache.geode.cache.execute">EmptyRegionFunctionException</a></td> |
| <td class="colLast"> |
| <div class="block">Exception to indicate that Region is empty for data aware functions.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/FunctionException.html" title="class in org.apache.geode.cache.execute">FunctionException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown to indicate an error or exceptional condition during the execution of |
| <a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute">Function</a>s in GemFire.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../../../org/apache/geode/cache/execute/FunctionInvocationTargetException.html" title="class in org.apache.geode.cache.execute">FunctionInvocationTargetException</a></td> |
| <td class="colLast"> |
| <div class="block">Thrown if one of the function execution nodes goes away or cache is closed.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package.description"> |
| <!-- --> |
| </a> |
| <h2 title="Package org.apache.geode.cache.execute Description">Package org.apache.geode.cache.execute Description</h2> |
| <div class="block"><p> |
| The <code>org.apache.geode.cache.execute</code> package provides APIs used |
| for function execution on gemfire system members. |
| </p> |
| <p> |
| GemFire's Function Execution Service supports execution of user-defined methods on targeted GemFire system members. |
| <br> |
| The fundamental premise is to route the function transparently to the GemFire system member that hosts the |
| data subset required by the application function and avoid moving data around on the network. |
| Application function can be executed on just one fabric node, executed in parallel on a subset |
| of nodes or in parallel across all the nodes. <br> |
| </p> |
| <p> |
| The Function Execution Service API is based on the following classes and interfaces which work together |
| to provide the function execution capability. The API allows execution of functions that are |
| "data dependent" or "data independent". Data dependent functions are functions that need |
| access to the local data set, on the targeted member. |
| <ul> |
| <li>The FunctionService class provides methods to execute functions on targeted GemFire |
| system members.</li> |
| |
| <li>Functions are java classes that implement the <a href="../../../../../org/apache/geode/cache/execute/Function.html" title="interface in org.apache.geode.cache.execute"><code>Function</code></a> interface. Functions |
| can be registered with the <a href="../../../../../org/apache/geode/cache/execute/FunctionService.html" title="class in org.apache.geode.cache.execute">Function Execution Service</a>.</li> |
| |
| <li>The application obtains the execution object <a href="../../../../../org/apache/geode/cache/execute/Execution.html" title="interface in org.apache.geode.cache.execute"><code>Execution</code></a> and uses its methods to target |
| execution.</li> |
| |
| <li>Calling the execute() method on the Execution object |
| starts the execution on the targeted Gemfire system |
| member(s).</li> |
| |
| <li>Upon execution on the targeted member(s), a FunctionContext |
| object is passed into the execute() method. Application developer can |
| use FunctionContext to get the arguments passed into the execution |
| of the function and references to the data regions providing access to the |
| local dataset as well as colocated dataset on the member.</li> |
| |
| <li>The Application developer can get ResultSender from FunctionContext |
| and send the results in parts to ResultCollector. As the result is sent, |
| it is added to the ResultCollector immediately. By default GemFire returns a ResultCollector, |
| whose getResult() method blocks until all the results have been obtained from the function |
| execution. To stop ResultCollector from waiting for more results a last result must be sent. |
| </li> |
| </ul> |
| |
| <p> |
| Example of a "data dependent" execution using the Function Execution Service |
| <pre> |
| Region region; |
| Set keySet = Collections.singleton("myKey"); |
| Function multiGetFunction; |
| Object args; |
| ResultCollector rc = FunctionService.onRegion(region) |
| .setArguments(args) |
| .withFilter(keySet) |
| .withCollector(new MyCustomResultCollector()) |
| .execute(multiGetFunction.getId()); |
| // Application can do something else here before retrieving the result |
| // It can even get deal with partial results which it will get in |
| // MyCustomResultCollector.addResult(). |
| |
| Object functionResult = rc.getResult(); |
| </pre> |
| </p> |
| |
| <p> |
| Example of a Function execution on a set of regions |
| <pre> |
| Region region1, region2, region3; |
| Set s = new HashSet(); |
| s.add(region1); |
| s.add(region2); |
| s.add(region3); |
| Function multiGetFunction; |
| Object args; |
| ResultCollector rc = FunctionService.onRegions(s) |
| .setArguments(args) |
| .withCollector(new MyCustomResultCollector()) |
| .execute(multiGetFunction.getId()); |
| // Application can get the handle of all the regions at the node it is executing on. |
| // This way it can get the handle of data in an efficient way. |
| Object functionResult = rc.getResult(); |
| </pre> |
| </p> |
| |
| |
| <p> |
| Example of a "data independent" execution using the Function |
| Execution Service |
| <pre> |
| DistributedSystem ds; |
| Function memberSetupFunction; |
| Object args; |
| ResultCollector rc = FunctionService.onMembers(ds) |
| .setArguments(args) |
| .execute(memberSetupFunction.getId()); |
| //Application can do something else here before retrieving the result |
| Object functionResult = rc.getResult(); |
| </pre> |
| </p> |
| |
| <p> |
| Example of a "Function" to be executed which sends result to ResultCollector using ResultSender. |
| <pre> |
| |
| public class MYFunction extends FunctionAdapter { |
| |
| public void execute(FunctionContext context) { |
| for(int i =0 ;i< 10; i++) |
| context.getResultSender().sendResult(i); |
| context.getResultSender.lastResult(10); |
| } |
| |
| public String getId() { |
| return "MYFunction"; |
| } |
| |
| public boolean hasResult() { |
| return true; |
| } |
| |
| } |
| </pre> |
| </p> |
| |
| <p> |
| Some scenarios where function execution can be useful: |
| <ol> |
| <li>Any arbitrary aggregation operation that requires iteration over |
| local data sets done more efficiently through a single call |
| to the cache server</li> |
| <li> Application wants to execute a server side behaviour.</li> |
| <li> Application wants to operate on many regions at a time. Like having function which need data from many regions. This can be |
| achieved in an efficient way using function service.</li> |
| <li> Application wants to initialize some of its components once on |
| each server which might be used later by executed functions, for example initialization of a 3rd party service.</li> |
| </ol> |
| </p></div> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../../../overview-summary.html">Overview</a></li> |
| <li class="navBarCell1Rev">Package</li> |
| <li>Class</li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../../../index-all.html">Index</a></li> |
| <li><a href="../../../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li><a href="../../../../../org/apache/geode/cache/control/package-summary.html">Prev Package</a></li> |
| <li><a href="../../../../../org/apache/geode/cache/lucene/package-summary.html">Next Package</a></li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../../../index.html?org/apache/geode/cache/execute/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| </body> |
| </html> |
