1 // $Id: IConnectionScoped.java 1281 2007-05-29 19:48:07Z grro $ 2 /* 3 * Copyright (c) xsocket.org, 2006 - 2007. All rights reserved. 4 * 5 * This library is free software; you can redistribute it and/or 6 * modify it under the terms of the GNU Lesser General Public 7 * License as published by the Free Software Foundation; either 8 * version 2.1 of the License, or (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 * Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public 16 * License along with this library; if not, write to the Free Software 17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 * 19 * Please refer to the LGPL license at: http://www.gnu.org/copyleft/lesser.txt 20 * The latest copy of this software may be found on http://www.xsocket.org/ 21 */ 22 23 package org.xsocket.stream; 24 25 26 27 28 /** 29 * Defines that the {@link IHandler} is connection scoped. 30 * A connection scoped handler will be used by the server 31 * as a prototype. That means, for each new incomming connection 32 * this handler will be cloned and the cloned handler will be assigned 33 * to the new connection to perform the handling. <br> 34 * The prototype handler will never be used to handle 35 * connections. It will only be used as a clone base. <br><br> 36 * 37 * By having such a dedicate handler instance for each connection, 38 * all variables of the cloned handler become session specific 39 * variables. <br><br> 40 * 41 * Take care by implementing the clone interface. Just calling the 42 * super.clone() method within the handler clone method lead to 43 * a shallow copy. That means all fields that refer to other 44 * objects will point to the same objects in both the original and 45 * the clone. To avoid side effects a deep copy has to be implemented. 46 * All attributes beside primitives, immutable or global manager/service 47 * references has also to be cloned 48 * <br> 49 * E.g. 50 * <pre> 51 * 52 * class MyHandler implements IDataHandler, IConnectionScoped { 53 * private int state = 0; 54 * private ConnectionRecordQueue recordQueue = new ConnectionRecordQueue(); 55 * ... 56 * 57 * 58 * public boolean onData(INonBlockingConnection connection) throws IOException, BufferUnderflowException { 59 * ... 60 * return true; 61 * } 62 * 63 * 64 * @Override 65 * public Object clone() throws CloneNotSupportedException { 66 * MyHandler copy = (MyHandler) super.clone(); 67 * copy.recordQueue = new ConnectionRecordQueue(); // deep clone! 68 * return copy; 69 * } 70 * } 71 * </pre> 72 73 * 74 * @author grro@xsocket.org 75 */ 76 public interface IConnectionScoped extends Cloneable { 77 78 /** 79 * {@inheritDoc} 80 */ 81 public Object clone() throws CloneNotSupportedException; 82 } 83