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 }