Synchronized


1   //$Id: Resource.java 1049 2007-03-21 16:42:48Z grro $
2   
3   /*
4    *  Copyright (c) xsocket.org, 2006 - 2007. All rights reserved.
5    *
6    *  This library is free software; you can redistribute it and/or
7    *  modify it under the terms of the GNU Lesser General Public
8    *  License as published by the Free Software Foundation; either
9    *  version 2.1 of the License, or (at your option) any later version.
10   *
11   *  This library is distributed in the hope that it will be useful,
12   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
13   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14   *  Lesser General Public License for more details.
15   *
16   *  You should have received a copy of the GNU Lesser General Public
17   *  License along with this library; if not, write to the Free Software
18   *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
19   *
20   * Please refer to the LGPL license at: http://www.gnu.org/copyleft/lesser.txt
21   * The latest copy of this software may be found on http://www.xsocket.org/
22   */
23  package org.xsocket;
24  
25  import java.lang.annotation.ElementType  ;
26  import java.lang.annotation.Retention  ;
27  import java.lang.annotation.RetentionPolicy  ;
28  import java.lang.annotation.Target  ;
29  
30  
31  
32  
33  /**
34   * The synchronized annotation determines the synchronization scope of an entity. For
35   * xSocket the synchronized annotation can only be used within a {@link IHandler} 
36   * class of the stream package. <br>
37   * 
38   * By default the handler of the stream package is synchronized on the connection level.
39   * That means, for the same connection the handler callback methods will be called in a 
40   * serialized manner. Sometime it is desirable that the synchronization should be done 
41   * by the handler itself. The synchronization can be deactivated by annotate the handler 
42   * as non-synchronized (level OFF). By switching off the synchronization, the correct 
43   * order of the call back method calls is not guaranteed. Because the call back method 
44   * will be performed within unsynchronized worker threads, race condition could occur. <br>
45   * 
46   *  E.g.
47   *  
48   * <pre>
49   *  ... 
50   *  import static org.xsocket.Synchronized.Mode.*;
51   *  import org.xsocket.Synchronized;
52   *  import org.xsocket.stream.BlockingConnection;
53   * 
54   * 
55   *  &#064Synchronized(OFF)   // deactivate the synchronization by setting scope OFF
56   *  class MyHandler implements IDataHandler {
57   *
58   *     public boolean onData(INonBlockingConnection connection) throws IOException, BufferUnderflowException {
59   *         ...
60   *         synchronized (connection) {
61   *              ByteBuffer[] data = connection.readByteBufferByDelimiter(DELIMITER);
62   *              ...
63   *         }
64   *         ...
65   *         
66   *         return true;
67   *     }
68   *  }
69   * </pre> 
70   * 
71   * 
72   * @author grro@xsocket.org
73   */
74  @Target  (ElementType.TYPE)
75  @Retention  (RetentionPolicy.RUNTIME)
76  public @interface Synchronized {
77      
78      public enum Mode { OFF, CONNECTION }
79      
80      Mode value() default Mode.CONNECTION;
81  }
82
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags