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 }