KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > sync4j > framework > server > session > SessionHandler


1 /**
2  * Copyright (C) 2003-2005 Funambol
3  *
4  *This program is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation; either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  */
18 package sync4j.framework.server.session;
19
20 /**
21  * This class represents the handler for a SyncML session. It coordinates and
22  * handles the packages and messages as dictated by the protocol.
23  * <p>
24  * The entry point is <i>processMessage()</i>, which determines which message is
25  * expected and what processing has to be done (depending on the value of
26  * <i>currentState</i>).
27  * <p>
28  * <i>SessionHandler</i> makes use of a <i>SyncEngine</i> for all
29  * tasks not related to the handling of the protocol.
30  * See <i>sync4j.framework.engine.SyncEngine</i> for more information.
31  *
32  * @see sync4j.framework.engine.SyncEngine
33  *
34  * @author Stefano Fornari @ Funambol
35  * @version $Id: SessionHandler.java,v 1.17 2005/03/02 20:57:38 harrie Exp $
36  */
37
38 import sync4j.framework.core.*;
39 import sync4j.framework.protocol.*;
40 import sync4j.framework.server.error.InvalidCredentialsException;
41 import sync4j.framework.engine.pipeline.MessageProcessingContext;
42 import sync4j.framework.engine.MessageSizeCalculator;
43 import sync4j.framework.server.error.ServerFailureException;
44
45 /**
46  * This interface represent the functionality a session object must provide.
47  * Different implementations can provide their own policy, but they have to be
48  * compliant at least to this contract.
49  */
50 public interface SessionHandler {
51
52     // --------------------------------------------------------------- Constants
53
54     public static final int STATE_START = 0x0000;
55     public static final int STATE_END = 0x0001;
56     public static final int STATE_PKG1_RECEIVING = 0x0002;
57     public static final int STATE_PKG1_RECEIVED = 0x0003;
58     public static final int STATE_PKG3_RECEIVING = 0x0004;
59     public static final int STATE_PKG3_RECEIVED = 0x0005;
60     public static final int STATE_SESSION_ABORTED = 0xFF01;
61     public static final int STATE_ERROR = 0xFFFF;
62
63
64     // ----------------------------------------------------------- publi methods
65
66
67     public String JavaDoc getSessionId();
68
69     /**
70      * The session a new session?
71      *
72      * @return true if the session is new, false otherwise
73      */
74     public boolean isNew();
75
76     public void setNew(boolean newSession);
77
78     /**
79      * Returns true if the sessione has been authenticated.
80      *
81      * @return true if the sessione has been authenticated, false otherwise
82      */
83     public boolean isAuthenticated();
84
85     /**
86      * Processes the given message. See the class description for more
87      * information.
88      *
89      * @param message the message to be processed
90      *
91      * @return the response message
92      *
93      * @throws ProtocolException in case of a protocol error
94      * @throws InvalidCredentialsException in case of invalid credentials
95      * @throws ServerFailureException in case of an internal server error
96      */
97     public SyncML processMessage(SyncML message, MessageProcessingContext context)
98     throws ProtocolException, InvalidCredentialsException, ServerFailureException;
99
100     /**
101      * Processes an error condition. This method is called when the error is
102      * is not fatal and is manageable at a protocol/session level so that a
103      * well formed SyncML message can be returned.
104      * <p>
105      * Note that the offending message <i>msg</i> cannot be null, meaning that
106      * at least the incoming message was a SyncML message. In this context,
107      * <i>RepresentationException</i>s are excluded.
108      *
109      * @param the offending message - NOT NULL
110      * @param the exception representing the error condition - NOT NULL
111      *
112      * @throws sync4j.framework.core.Sync4jException in case of unexpected errors
113      *
114      * @return the response message
115      */
116     public SyncML processError(SyncML msg, Throwable JavaDoc error)
117     throws Sync4jException;
118
119     /**
120      * Called by the <i>SessionManager</i> when the session is expired.
121      * It logs out the credential and release aquired resources.
122      */
123     public void expire();
124
125     /**
126      * Gets the creation timestamp of the session
127      */
128     public long getCreationTimestamp();
129
130     /**
131      * Indicates that the current session successfully ended. The synch-
132      * ronization can be finalized and committed.
133      */
134     public void commit();
135
136     /**
137      * Indicates that the current session must be forced to end without
138      * commiting the work (note that this does not automatically mean that the
139      * synchronization is rolled back).
140      *
141      * @param statusCode the reason for the aborting
142      */
143     public void abort(int statusCode);
144
145     /**
146      * Gets the current state
147      *
148      * @return the current state
149      */
150     public int getCurrentState();
151
152     /**
153      * Set the size calculator to use to calculate messages size.
154      *
155      * @param calculator the calculator
156      */
157     public void setSizeCalculator(MessageSizeCalculator calculator);
158
159 }
160
161
Popular Tags