1 package org.apache.helix;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.List;
23 import java.util.Map;
24
25 import org.apache.helix.messaging.AsyncCallback;
26 import org.apache.helix.messaging.handling.MessageHandlerFactory;
27 import org.apache.helix.model.Message;
28
29 /**
30 * Provides the ability to <br>
31 * <li>Send message to a specific component in the cluster[ participant,
32 * controller, Spectator(probably not needed) ]</li> <li>Broadcast message to all
33 * participants</li> <li>Send message to instances that hold a specific resource</li>
34 * <li>Asynchronous request response api. Send message with a co-relation id and
35 * invoke a method when there is a response. Can support timeout.</li>
36 *
37 */
38 public interface ClusterMessagingService
39 {
40 /**
41 * Send message matching the specifications mentioned in recipientCriteria.
42 *
43 * @param receipientCriteria
44 * @See Criteria
45 * @param message
46 * message to be sent. Some attributes of this message will be
47 * changed as required
48 * @return returns how many messages were successfully sent.
49 */
50 int send(Criteria recipientCriteria, Message message);
51
52 /**
53 * This will send the message to all instances matching the criteria<br>
54 * When there is a reply to the message sent AsynCallback.onReply will be
55 * invoked. Application can specify a timeout on AsyncCallback. After every
56 * reply is processed AsyncCallback.isDone will be invoked.<br>
57 * This method will return after sending the messages. <br>
58 * This is useful when message need to be sent and current thread need not
59 * wait for response since processing will be done in another thread.
60 *
61 * @param receipientCriteria
62 * @param message
63 * @param callbackOnReply
64 * @param timeOut
65 * @param retryCount
66 * @return
67 */
68 int send(Criteria receipientCriteria, Message message,
69 AsyncCallback callbackOnReply, int timeOut);
70
71 int send(Criteria receipientCriteria, Message message,
72 AsyncCallback callbackOnReply, int timeOut, int retryCount);
73
74 /**
75 * This will send the message to all instances matching the criteria<br>
76 * When there is a reply to the message sent AsynCallback.onReply will be
77 * invoked. Application can specify a timeout on AsyncCallback. After every
78 * reply is processed AsyncCallback.isDone will be invoked.<br>
79 * This method will return only after the AsyncCallback.isDone() returns true <br>
80 * This is useful when message need to be sent and current thread has to wait
81 * for response. <br>
82 * The current thread can use callbackOnReply instance to store application
83 * specific data.
84 *
85 * @param receipientCriteria
86 * @param message
87 * @param callbackOnReply
88 * @param timeOut
89 * @param retryCount
90 * @return
91 */
92 int sendAndWait(Criteria receipientCriteria, Message message,
93 AsyncCallback callbackOnReply, int timeOut);
94
95 int sendAndWait(Criteria receipientCriteria, Message message,
96 AsyncCallback callbackOnReply, int timeOut, int retryCount);
97
98 /**
99 * This will register a message handler factory to create handlers for
100 * message. In case client code defines its own message type, it can define a
101 * message handler factory to create handlers to process those messages.
102 * Messages are processed in a threadpool which is hosted by cluster manager,
103 * and cluster manager will call the factory to create handler, and the
104 * handler is called in the threadpool.
105 *
106 * Note that only one message handler factory can be registered with one
107 * message type.
108 *
109 * @param type
110 * The message type that the factory will create handler for
111 * @param factory
112 * The per-type message factory
113 * @param threadpoolSize
114 * size of the execution threadpool that handles the message
115 * @return
116 */
117 public void registerMessageHandlerFactory(String type,
118 MessageHandlerFactory factory);
119
120 /**
121 * This will generate all messages to be sent given the recipientCriteria and MessageTemplate,
122 * the messages are not sent.
123 *
124 * @param receipientCriteria
125 * @param messageTemplate
126 * @return
127 */
128 public Map<InstanceType, List<Message>> generateMessage(final Criteria recipientCriteria,
129 final Message messageTemplate);
130
131 }