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.context.RpcManager;
19 import fulmine.model.container.IContainer;
20 import fulmine.model.field.IField;
21
22 /**
23 * Represents the result from invoking a specific RPC in a remote context. The
24 * result encapsulates either the RPC return value or any exception string
25 * raised when the RPC was handled in the remote context.
26 * <p>
27 * The {@link #isSuccessful()} method should be examined before calling either
28 * {@link #getResult()} or {@link #getExceptionMessage()}. Both
29 * {@link #getResult()} and {@link #getExceptionMessage()} are mutually
30 * exclusive and when not applicable, these methods may return <code>null</code>
31 * . This is why is it important to call {@link #isSuccessful()} to determine
32 * which of these methods to interrogate for the result status.
33 * <p>
34 * Results are transmitted back to the remote callers in result records. A
35 * result record is an {@link IContainer}. These are subsequently converted into
36 * {@link IRpcResult} objects.
37 *
38 * @see RpcManager
39 * @author Ramon Servadei
40 */
41 public interface IRpcResult
42 {
43 /**
44 * The name of the field in the result record for the RPC marker.
45 *
46 * @see IRpcResultHandler
47 */
48 String MARKER = "marker";
49
50 /**
51 * The name of the field in the result record for the
52 * {@link #isSuccessful()} attribute
53 */
54 String IS_SUCCESSFUL = "success";
55
56 /**
57 * The name of the field in the result record for the {@link #getResult()}
58 * attribute
59 */
60 String RESULT = "result";
61
62 /**
63 * The name of the field in the result record for the
64 * {@link #getExceptionMessage()} attribute
65 */
66 String EXCEPTION = "exception";
67
68 /**
69 * Determine whether the RPC was successfully executed. If it was
70 * successful, calling {@link #getResult()} will return the result from the
71 * RPC. If it was not successful, calling {@link #getExceptionMessage()}
72 * will return a reason why the RPC was not successful.
73 *
74 * @return <code>true</code> if the RPC was successfully executed.
75 */
76 boolean isSuccessful();
77
78 /**
79 * Get the result from the RPC
80 *
81 * @return the result from the RPC or <code>null</code> if the RPC was not
82 * successful
83 * @see #isSuccessful()
84 */
85 IField getResult();
86
87 /**
88 * Get the exception message if the RPC was not executed successfully. This
89 * can either be due to local context issues or a problem when the RPC was
90 * executing in the remote context.
91 *
92 * @return the exception message if the RPC was not executed successfully,
93 * or <code>null</code> if the RPC was successful
94 * @see IRpcResult#isSuccessful()
95 */
96 String getExceptionMessage();
97
98 /**
99 * Get the marker for the RPC invocation this result is for. This allows
100 * remote callers to track the results for multiple calls to the same RPC.
101 *
102 * @return the marker for the RPC invocation this result is for
103 * @see IRpcManager#invoke(IRpcResultHandler, String, String, IField...)
104 */
105 IRpcMarker getMarker();
106
107 /**
108 * Update the RPC's result record with the data from this result instance.
109 *
110 * @param marker
111 * the marker for the RPC call this result is for
112 * @param resultRecord
113 * the result record for the RPC this result is for
114 */
115 void updateResultRecord(IRpcMarker marker, IContainer resultRecord);
116 }