1 /*
2 Copyright 2008 Ramon Servadei
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16 package fulmine.rpc;
17
18 import fulmine.ILifeCycle;
19 import fulmine.model.field.IField;
20
21 /**
22 * The manager for the Remote Procedure Call (RPC) framework. This provides the
23 * following facilities for application code:
24 * <ol>
25 * <li>it allows application code to invoke procedures exposed by other remote
26 * contexts
27 * <li>it allows application code to publish procedures that can be invoked by
28 * other remote contexts
29 * </ol>
30 * Application code should register an {@link IRpcPublicationListener} to
31 * receive events when remote procedures are published or unpublished.
32 *
33 * @author Ramon Servadei
34 */
35 public interface IRpcManager extends ILifeCycle, IRpcPublishOperations
36 {
37 /**
38 * Defines the system property name for the RPC timeout. This value is
39 * expressed in milliseconds.
40 *
41 * @see IRpcManager#DEFAULT_RPC_TIMEOUT
42 */
43 public static final String RPC_TIMEOUT = "RpcManager.rpcTimeout";
44
45 /** The default value for the {@link RPC_TIMEOUT} */
46 public static final String DEFAULT_RPC_TIMEOUT = "30000";
47
48 /**
49 * Add a listener for RPC publication events. This will be activated when an
50 * RPC publication event is received from any connected remote context.
51 * <p>
52 * This is an idempotent operation.
53 *
54 * @param remoteContextIdentity
55 * the remote context to monitor for RPC publish/unpublish events
56 * @param listener
57 * a listener to receive the RPC publish/unpublish events.
58 *
59 * @return <code>true</code> if the listener was added, <code>false</code>
60 * otherwise
61 */
62 boolean addRpcPublicationListener(String remoteContextIdentity,
63 IRpcPublicationListener listener);
64
65 /**
66 * Remove an RPC publication listener. The listener will no longer receive
67 * notifications when RPC publish/unpublish events occur. *
68 * <p>
69 * This is an idempotent operation.
70 *
71 * @param remoteContextIdentity
72 * the remote context that the listener was monitoring for RPC
73 * publish/unpublish events
74 * @param listener
75 * the listener to remove
76 *
77 * @return <code>true</code> if the listener was found and removed,
78 * <code>false</code> otherwise
79 */
80 boolean removeRpcPublicationListener(String remoteContextIdentity,
81 IRpcPublicationListener listener);
82
83 /**
84 * Synchronously invoke the RPC in the named remote context. <b>This method
85 * will block until a result is returned or a timeout occurs.</b>
86 * <p>
87 * It is assumed that this method is called after an RPC publication event
88 * is received by an {@link IRpcPublicationListener}.
89 *
90 * @param remoteContextIdentity
91 * the remote context to invoke the RPC in
92 * @param procedure
93 * the RPC name
94 * @param args
95 * the arguments for the RPC
96 * @return the result from the RPC
97 * @see #RPC_TIMEOUT
98 */
99 IRpcResult invoke(String remoteContextIdentity, String procedure,
100 IField... args);
101
102 /**
103 * Asynchronously invoke the RPC in the named remote context. It is assumed
104 * that this method is called after an RPC publication event is received by
105 * an {@link IRpcPublicationListener}
106 *
107 * @param resultHandler
108 * the handler to process the asynchronous result
109 * @param remoteContextIdentity
110 * the remote context to invoke the RPC in
111 * @param procedure
112 * the RPC name
113 * @param args
114 * the arguments for the RPC
115 *
116 * @return a marker that allows the resultHandler to tie up the result from
117 * this specific RPC invocation
118 */
119 IRpcMarker invoke(IRpcResultHandler resultHandler,
120 String remoteContextIdentity, String procedure, IField... args);
121
122 }