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 /**
19 * Exposes publish and unpublish operations for RPCs. Used as a common holder of
20 * publish and unpublish methods required in separate RPC class hierarchies.
21 *
22 * @author Ramon Servadei
23 */
24 public interface IRpcPublishOperations
25 {
26 /**
27 * Publish the named procedure to all known remote contexts.
28 * <p>
29 * There can only be one handler per procedure instance. Different handlers
30 * can be used for overloaded procedures. RPC definitions cannot overload
31 * the result type, if this method is called with a definition that attempts
32 * to overload the result type, the operation is ignored and no publish
33 * happens.
34 * <p>
35 * After this method has completed, remote contexts will be able to invoke
36 * the RPC.
37 *
38 * @param handler
39 * the object that will handle any RPC invocations for this RPC
40 * definition. <b>This object must be thread safe.</b>
41 * @param rpcDefinition
42 * the RPC definition
43 * @return <code>true</code> if the procedure was published,
44 * <code>false</code> if has already been published
45 */
46 boolean publishProdedure(IRpcHandler handler, IRpcDefinition rpcDefinition);
47
48 /**
49 * Unpublish the procedure from all connected remote contexts.
50 *
51 * @param rpcDefinition
52 * the RPC definition to unpublish
53 *
54 * @return <code>true</code> if the procedure was unpublished
55 */
56 boolean unpublishProdedure(IRpcDefinition rpcDefinition);
57
58 /**
59 * Allows application code to remotely enable all methods in a handler
60 * object that are implementations of methods in an interface definition.
61 * This essentially publishes these methods as RPCs for other contexts to
62 * invoke.
63 * <p>
64 * There are some caveats to methods that can be remotely enabled; the
65 * method arguments and return types must be scalar and only the following
66 * types are supported:
67 * <ul>
68 * <li>integer
69 * <li>long
70 * <li>float
71 * <li>double
72 * <li>boolean
73 * <li>String
74 * </ul>
75 * <p>
76 * This is a convenience method in-lieu of calling
77 * {@link #publishProdedure(IRpcHandler, IRpcDefinition)}.
78 *
79 * @param definition
80 * an interface that defines all the methods in the handler that
81 * should be remotely enabled. This includes all methods in the
82 * super-interfaces, if any.
83 * @param handler
84 * the object that implements the methods declared in the
85 * definition interface. The handler does not necessarily have to
86 * be an instance of the interface (i.e. does not need to
87 * explicitly implement the interface, it only needs to implement
88 * all the methods). All remote invocations of these methods will
89 * be handled by this object. <b>The remotely enabled methods
90 * must be thread safe.</b>
91 * @return <code>true</code> if all methods were successfully published
92 * @throws IllegalArgumentException
93 * if the handler does not implement all methods declared in the
94 * definition
95 */
96 boolean publishRpcs(Class<?> definition, Object handler);
97
98 /**
99 * Allows application code to remove any previously remotely enabled methods
100 * published via {@link #publishRpcs(Class, Object)}
101 *
102 * @param definition
103 * an interface that defines all the methods in the handler that
104 * should be remotely disabled. This includes all methods in the
105 * super-interfaces, if any.
106 * @param handler
107 * the object that implements the methods declared in the
108 * definition interface. These methods will no longer be
109 * available for remote invocation.
110 * @return <code>true</code> if all methods were successfully unpublished
111 */
112 boolean unpublishRpcs(Class<?> definition, Object handler);
113 }