1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.directory.mitosis.service;
21
22
23 import org.apache.directory.mitosis.common.Replica;
24 import org.apache.directory.mitosis.configuration.ReplicationConfiguration;
25 import org.apache.directory.mitosis.service.protocol.handler.ReplicationClientContextHandler;
26 import org.apache.directory.mitosis.service.protocol.handler.ReplicationContextHandler;
27 import org.apache.directory.mitosis.service.protocol.handler.ReplicationServerContextHandler;
28 import org.apache.directory.server.core.DirectoryService;
29 import org.apache.mina.common.IoSession;
30
31
32 /**
33 * A <a href="http://www.corej2eepatterns.com/Patterns2ndEd/ContextObject.htm">context object</a>
34 * that provides the functions required for a client or a server to implement
35 * networking code related with replication communication. This is provided
36 * to and used by {@link ReplicationClientContextHandler} and
37 * {@link ReplicationServerContextHandler}.
38 *
39 * @author The Apache Directory Project Team
40 */
41 public interface ReplicationContext
42 {
43 /**
44 * Returns <a href="http://mina.apache.org/">MINA</a> {@link IoSession}
45 * instance that is associated with the current connection to
46 * the remote {@link Replica}.
47 */
48 IoSession getSession();
49
50 /**
51 * Returns the current {@link ReplicationConfiguration} of the
52 * {@link Replica} which is managing this context.
53 */
54 ReplicationConfiguration getConfiguration();
55
56 /**
57 * Returns the {@link ReplicationInterceptor} which is managing this
58 * context.
59 */
60 ReplicationInterceptor getService();
61
62
63 /**
64 * Returns the {@link DirectoryService} which owns the {@link ReplicationInterceptor}
65 * which is managing this context.
66 */
67 DirectoryService getDirectoryService();
68
69
70 /**
71 * Generates a new and unique sequence number of protocol message.
72 * @return the new sequence number.
73 */
74 int getNextSequence();
75
76
77 /**
78 * Returns the remote peer {@link Replica} that this context is connected
79 * to.
80 */
81 Replica getPeer();
82
83
84 /**
85 * Sets the remote peer {@link Replica} that this context is connected
86 * to. A user has authenticate the remote peer first and call this method
87 * manually to prevent unauthorized access.
88 */
89 void setPeer( Replica peer );
90
91 /**
92 * Returns the current state of the {@link Replica} this context is
93 * managing.
94 */
95 State getState();
96
97 /**
98 * Sets the current state of the {@link Replica} this context is
99 * managing.
100 */
101 void setState( State state );
102
103
104 /**
105 * Schedules an expiration of the specified <tt>message</tt>. A user of
106 * this context could call this method with the message it has written out
107 * to the remote peer. If {@link #cancelExpiration(int)} method is not
108 * invoked within a certain timeout, an exception will be raised to
109 * {@link ReplicationContextHandler#exceptionCaught(ReplicationContext, Throwable)}.
110 */
111 void scheduleExpiration( Object message );
112
113 /**
114 * Cancels the expiration scheduled by calling
115 * {@link #scheduleExpiration(Object)}. A user of this context could
116 * call this method when the response message has been received to
117 * stop the expiration for the message with the specified
118 * <tt>sequence</tt> number.
119 *
120 * @return the request message with the specified <tt>sequence</tt> number
121 */
122 Object cancelExpiration( int sequence );
123
124 /**
125 * Cancells all scheduled expirations. A user of this context could
126 * call this method when the current connection is closed.
127 */
128 void cancelAllExpirations();
129
130 /**
131 * Returns the number of the scheduled experations. A user of this
132 * contexst could check this value before sending a new message to the
133 * remote peer to prevent {@link OutOfMemoryError} by limiting the number
134 * of the messages which didn't get their responses.
135 */
136 int getScheduledExpirations();
137
138
139 /**
140 * Forces this context to send replication data to the peer replica immediately.
141 *
142 * @return <tt>true</tt> if the replication has been started,
143 * <tt>false</tt> if the replication didn't start because
144 * the replication process is already in progress or
145 * the client is currently logging in to the server yet.
146 */
147 boolean replicate();
148
149 /**
150 * Represents the state of the connection between two {@link Replica}s.
151 *
152 * @author The Apache Directory Project Team
153 */
154 public enum State
155 {
156 /**
157 * Connection is established.
158 */
159 INIT,
160
161 /**
162 * Client has logged in and is ready to exchange information.
163 */
164 READY,
165 ;
166 }
167 }