1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2001,2008 Oracle.  All rights reserved.
5 *
6 * $Id: Sequence.java,v 12.7 2008/01/17 05:04:53 mjc Exp $
7 */
8
9package com.sleepycat.db;
10
11import com.sleepycat.db.internal.DbConstants;
12import com.sleepycat.db.internal.DbSequence;
13
14/**
15A Sequence handle is used to manipulate a sequence record in a database.
16Sequence handles are opened using the {@link com.sleepycat.db.Database#openSequence Database.openSequence} method.
17*/
18public class Sequence {
19    private DbSequence seq;
20    private int autoCommitFlag;
21
22    /* package */
23    Sequence(final DbSequence seq, SequenceConfig config)
24        throws DatabaseException {
25
26        this.seq = seq;
27        seq.wrapper = this;
28        if (seq.get_db().get_transactional())
29                this.autoCommitFlag = DbConstants.DB_AUTO_COMMIT |
30                    (SequenceConfig.checkNull(config).getAutoCommitNoSync() ?
31                    DbConstants.DB_TXN_NOSYNC : 0);
32    }
33
34    /**
35    Close a sequence.  Any unused cached values are lost.
36    <p>
37    The sequence handle may not be used again after this method has been
38    called, regardless of the method's success or failure.
39    <p>
40    <p>
41@throws DatabaseException if a failure occurs.
42    */
43    public void close()
44        throws DatabaseException {
45
46        seq.close(0);
47    }
48
49    /**
50    Return the next available element in the sequence and changes the sequence
51    value by <code>delta</code>.  The value of <code>delta</code> must be
52    greater than zero.  If there are enough cached values in the sequence
53    handle then they will be returned.  Otherwise the next value will be
54    fetched from the database and incremented (decremented) by enough to cover
55    the <code>delta</code> and the next batch of cached values.
56    <p>
57    The <code>txn</code> handle must be null if the sequence handle was opened
58    with a non-zero cache size.
59    <p>
60    For maximum concurrency, a non-zero cache size should be specified prior to
61    opening the sequence handle, the <code>txn</code> handle should be
62    <code>null</code>, and {@link com.sleepycat.db.SequenceConfig#setAutoCommitNoSync SequenceConfig.setAutoCommitNoSync} should
63    be called to disable log flushes.
64    <p>
65    @param txn
66For a transactional database, an explicit transaction may be specified, or null
67may be specified to use auto-commit.  For a non-transactional database, null
68must be specified.
69    <p>
70    @param delta
71    the amount by which to increment or decrement the sequence
72    <p>
73    @return
74    the next available element in the sequence
75    */
76    public long get(Transaction txn, int delta)
77        throws DatabaseException {
78
79        return seq.get((txn == null) ? null : txn.txn, delta,
80            (txn == null) ? autoCommitFlag : 0);
81    }
82
83    /**
84    Return the Database handle associated with this sequence.
85    <p>
86    @return
87    The Database handle associated with this sequence.
88    */
89    public Database getDatabase()
90        throws DatabaseException {
91
92        return seq.get_db().wrapper;
93    }
94
95    /**
96    Return the DatabaseEntry used to open this sequence.
97    <p>
98    @return
99    The DatabaseEntry used to open this sequence.
100    */
101    public DatabaseEntry getKey()
102        throws DatabaseException {
103
104        DatabaseEntry key = new DatabaseEntry();
105        seq.get_key(key);
106        return key;
107    }
108
109    /**
110    Return statistical information about the sequence.
111    <p>
112    In the presence of multiple threads or processes accessing an active
113    sequence, the information returned by this method may be out-of-date.
114    <p>
115    The getStats method cannot be transaction-protected. For this reason, it
116    should be called in a thread of control that has no open cursors or active
117    transactions.
118    <p>
119    @param config
120    The statistics returned; if null, default statistics are returned.
121    <p>
122    @return
123    Sequence statistics.
124    */
125    public SequenceStats getStats(StatsConfig config)
126        throws DatabaseException {
127
128        return seq.stat(config.getFlags());
129    }
130}
131