View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.id.uuid.state;
19  
20  import java.io.IOException;
21  import java.io.Serializable;
22  import java.util.Set;
23  
24  
25  /**
26   * <p>The <code>State</code> interface. Implementors are responsible for storing
27   * UUIDGenerator stateful information. Each node contains the last timestamp,
28   * the last clock sequence used, and the node identifier bytes. The implementor
29   * should be prepared to load, store, and return the <code>Node</code>s from
30   * some stateful storage.</p>
31   *
32   * @author Commons-Id team
33   * @version $Id: State.java 480488 2006-11-29 08:57:26Z bayard $
34   */
35  public interface State extends Serializable {
36  
37      /** The default <code>State</code> implementation class name if not configured. */
38      String DEFAULT_STATE_IMPL = "org.apache.commons.id.uuid.state.ReadOnlyResourceStateImpl";
39  
40      /**
41       * <p>Method loads the Systems node identifier information usually from some
42       * stateful storage area.</p>
43       * <p><b>Note<b> each JVM instance should have a separate configuration since
44       * a system wide Mutex is not feasible, then in a system with multiple
45       * concurrent jvm instances running - each instance should utilize a different
46       * configuration with <b>distinct</b> node identifiers.</p>
47       *
48       * @throws IllegalStateException likely the system is not configured or the state of the system is incorrect.
49       */
50      void load(  ) throws Exception;
51  
52      /**
53       * <p>Returns the collection of <code>Nodes</code> for this uuid state
54       * information.</p>
55       *
56       * @return the collection of <code>Nodes</code> for this uuid state.
57       */
58      Set getNodes(  );
59  
60      /**
61       * <p>Stores the state information.</p>
62       *
63       * <p>To increase the quality of the UUID uniqueness, a system that may
64       * write to stable storage SHOULD perist the state of the UUIDGenerator in
65       * order to reduce the likelihood of duplicate identifiers and increase the
66       * quality of the identifiers generated.</p>
67       *
68       * @param nodes a Collection of <code>Node</code>s to store.
69       * @throws IOException - an input/output Exception perhaps due to StringBuffer#append
70       */
71      void store( Set nodes ) throws IOException;
72  
73      /**
74       * <p>Stores the state information using a predetermined timestamp. This timestamp should be a time in the future but a shorter
75       * period than what the java virtual machine can restart within. This is normally linked to the sychInterval.</p>
76       * <p>Using a point in time in the near future reduces unnecessary I/O, while allowing for the persistent state to be stored
77       * periodically, in an efficient manner.</p>
78       *
79       * @param nodes a Collection of <code>Node</code>s to store.
80       * @param timestamp the timestamp to write all <code>Node</code>s last timestamp as.
81       */
82      void store( Set nodes, long timestamp );
83  
84      /**
85       * <p>Returns the number of milliseconds to wait between writing to stable storage.</p>
86       *
87       * @return the number of milliseconds to wait between writing to stable storage.
88       */
89      long getSynchInterval();
90  }