uidgen
Product: xTier™/LWC 2.3 Whitepaper: n/a	support@fitechlabs.com  Download  Buy
Depends: log  Related: n/a
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
'uidgen' service has 2 functional parts:

• Create numeric UID sequences.
• Create UIDs with different uniqueness strengh.

Persistent

In persistent UID sequences the sequence values are saved between starting and stopping of xTier™. 'uidgen' comes with predefined file-based persistence sink UidFileSink that should be sufficient for most of the cases.
Note that persistent sink only quarantees that values will not repeat upon restart. Depending on how xTier™ was stopped and value of saving frequency the sequence may have a gap in values upon starting next time.

Non-persistent

In non-persistence UID sequence values are not saved between xTier™ restarts and therefore they can repeat themselves upon restart.

Every sequence has following characteristics:

• Start value.
• End value.
• Step value. This value cannot be 0.
• Flag indicating whether or not current sequence is cyclic meaning that when last element in the sequence is reached it will return first element again.
• Frequency of saving sequence's value in its sink. This value only applies to persistent UID sequences. This parameter indicates how many sequence values have to be fetched before sequence stores its current value. For example, if frequence is 1 that sequence will store its current value on each step which will ensure that there will be no gaps but will severely impact the performance.

For example, if we have sequence with parameters:

• Start value = 1000.
• End value = 900.
• Step = 40.
• Cycle flag is true.

We will have following sequence's values: 1000, 960, 920, 1000, 960...

• 8-bytes VM-wide pseudo-unique ID number.
• 16-bytes host-wide pseudo-unique ID number.
• 24-bytes LAN-wide pseudo-unique ID number.
• 32-bytes WAN-wide pseudo-unique ID number.

 Top

Configuration
Sequences and sinks objects are defined in xtier_uidgen.xml configuration file. This file follows standard xTier™ service configuration pattern that can be illustrated by the following complete example of 'uidgen' service configuration:

1		<!-- File UID sequence sink. -->
2		<ioc policy="singleton" uid="file.sink">
3		<java class="com.fitechlabs.xtier.services.
4		uidgen.sinks.UidFileSink">
5		<ctor>
6		<arg null="true"/>
7		</ctor>
8		</java>
9		</ioc>
10
11		<!-- UID persistant sequence declaration. -->
12		<seq name="id1" start="1" end="10000"
13		step="2" cycle="true">
14		<persistence>
15		<ioc ref-uid="file.sink"/>
16		</persistence>
17		</seq>
18
19		<!-- UID not persistant sequence declaration. -->
20		<seq name="id2" start="2" end="10" step="3"
21		cycle="true" freq="10"/>

'uidgen' service configuration consists of one or more sequence descriptor definitions specified by <seq> tag. Notice that sinks are defined as IoC objects. Formal specification for <uidgen> tag can be found at xtier_uidgen.dtd DTD file at ${XTIER_ROOT}/config/ dtd folder. <uidgen> tag defines following attributes and elements:

persistence	This element defines IoC descriptor for sink. Note that this attribute is optional.
name	This attribute defines unique name for sequence.
start	This attribute defines start value for sequence.
end	This attribute defines end value for sequence.
step	This attribute defines step of sequence. This value cannot be 0.
cycle	true or false. This attribute defines flag indicating whether or not current sequence is cyclic meaning that when last element in the sequence is reached it will return first element again.
freq	Frequency of saving sequence's value in its sink. This value only applies to persistent UID sequences. This parameter indicates how many sequence values have to be fetched before sequence stores its current value. For example, if frequence is 1 that sequence will store its current value on each step which will ensure that there will be no gaps but will severely impact the performance. Note that saving frequency is optional parameter. If it is not specified, the default value will be used.

 Top

Examples
Usage of 'uidgen' service follows the standard pattern of using xTier™ service: you need to obtain an instance of xTier™ kernel that serves as a service registry. Once you have xTier™ kernel you can get an instance of any service, in our case the 'uidgen' service (example assumes above configuration):

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'uidgen' service.
5		UidGenService uidgen = xtier. uidgen ();
6
7		// Fetch pre-configured UID sequences.
8		UidSeq seq1 = uidgen.getUidSeq(“id1”);
9		UidSeq seq2 = uidgen.getUidSeq(“id2”);
10
11		// Print first 4 sequence values.
12		System.out.println("id1[" + 0 + "] = " +
13		seq.getNext());
14		System.out.println("id1[" + 1 + "] = " +
15		seq.getNext());
16		System.out.println("id1[" + 2 + "] = " +
17		seq.getNext());
18		System.out.println("id1[" + 3 + "] = " +
19		seq.getNext());
20
21		// Makes 8-bytes VM-wide pseudo-unique ID number.
22		System.out.println("VM Id1: " + uidgen.makeVmUid());
23
24		// Makes 16-bytes host-wide pseudo-unique ID number.
25		System.out.println("Host Id1: " + uidgen.makeHostUid());
26
27		// Makes 24-bytes LAN-wide pseudo-unique ID number.
28		System.out.println("Lan Id1: " + uidgen.makeLanUid());
29
30		// Makes 32-bytes WAN-wide pseudo-unique ID number.
31		System.out.println("Wan Id1: " + uidgen.makeWanUid());

 Top