View Javadoc

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 }