1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
/*
* Copyright (c) 1998, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0,
* or the Eclipse Distribution License v. 1.0 which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
*/
// Contributors:
// Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.sequencing;
import org.eclipse.persistence.sessions.Login;
import org.eclipse.persistence.sessions.server.ConnectionPool;
/**
* <p>
* <b>Purpose</b>: Define an interface to control sequencing functionality.
* <p>
* <b>Description</b>: This interface is accessed through DatabaseSession.getSequencingControl().
* It allows to create, re-create, customize Sequencing object
* which is available through DatabaseSession.getSequencing()
* and provides sequencing values for all descriptors that use sequencing.
*
* Here's the lifecycle of Sequencing object used by DatabaseSession:
* 1. DatabaseSession created - sequencing object doesn't yet exist;
* 2. DatabaseSession.login() causes creation of Sequencing object;
* 3. DatabaseSession.logout() causes destruction of Sequencing object.
*
* In case sequencing object doesn't yet exist all the set parameters' values will be used
* during its creation.
*
* In case sequencing object already exists:
* 1. The following methods don't alter sequencing object - the corresponding parameters will only
* be used in case a new sequencing object is created:
* setShouldUseSeparateConnection;
* setLogin;
* setMinPoolSize;
* setMaxPoolSize.
* 2. The following methods cause immediate destruction of the sequencing object and creation of a new one:
* setValueGenerationPolicy;
* setShouldUseNativeSequencing;
* setShouldUseTableSequencing;
* resetSequencing;
* 3. The following methods cause change immediately:
* setPreallocationSize (next sequencing preallocation will use the set parameter's value).
* <p>
* <b>Responsibilities</b>:
* <ul>
* <li> Define the APIs for controlling sequencing.
* </ul>
* @see Sequence
* @see org.eclipse.persistence.sessions.DatabaseSession
*/
public interface SequencingControl {
/**
* ADVANCED:
* Immediately re-create sequencing object.
* The only reason to use this method is to pick up all parameters'
* values that were changed after the original sequencing object has been created.
*/
public void resetSequencing();
/**
* PUBLIC:
* Indicate whether separate connection(s) for sequencing could be used
* (by default it couldn't).
* If this flag is set to true then separate connection(s) for sequencing
* will be used in case getSequence().shouldUseSeparateConnection()
* returns true.
* @see Sequence
*/
public boolean shouldUseSeparateConnection();
/**
* PUBLIC:
* Set whether separate connection(s) for sequencing could be used
* (by default it couldn't).
* If this flag is set to true then separate connection(s) for sequencing
* will be used in case getSequence().shouldUseSeparateConnection()
* returns true.
* @see Sequence
*/
public void setShouldUseSeparateConnection(boolean shouldUseSeparateConnection);
/**
* PUBLIC:
* Indicates whether sequencing actually uses separate connection(s).
* Returns true if sequencing is connected and uses separate connection(s).
* Returns false if sequencing is not connected (getSequencing()==null).
* Note that if shouldUseSeparateConnection() returns false this method also returns false.
* However if shouldUseSeparateConnection() returns true this method
* returns false in the following two cases:
* <br>sequencing is not connected;
* <br>getSequence().shouldUseSeparateConnection() == false.
* @see Sequence
*/
boolean isConnectedUsingSeparateConnection();
/**
* ADVANCED:
* Return a DatabaseLogin to be used by separate sequencing connection(s).
* @see org.eclipse.persistence.sessions.DatabaseLogin
*/
Login getLogin();
/**
* ADVANCED:
* Returns a DatabaseLogin to be used by separate sequencing connection(s)
* The set value is ignored if shouldUseSeparateConnection() returns false.
* The DatabaseLogin *MUST*:
* 1. specify *NON-JTS* connections (such as NON_JTS driver or read-only datasource);
* 2. sequenceLogin.shouldUseExternalTransactionController()==false
* In case this method is not called, but separate connection should be used,
* sequencing will use a clone of login owned by the DatabaseSession,
* or a clone of read login owned by ServerSession.
* @see org.eclipse.persistence.sessions.DatabaseLogin
*/
void setLogin(Login login);
/**
* ADVANCED:
* Return the connection pool to use for sequencing.
*/
ConnectionPool getConnectionPool();
/**
* ADVANCED:
* Set the connection pool to use for sequencing.
*/
void setConnectionPool(ConnectionPool pool);
/**
* PUBLIC:
* Returns a minimum number of connections in sequencing connection pool.
* @see org.eclipse.persistence.sessions.server.ConnectionPool
* @see org.eclipse.persistence.sessions.server.ServerSession
*/
int getMinPoolSize();
/**
* PUBLIC:
* Sets a minimum number of connections in sequencing connection pool
* The set value is ignored if shouldUseSeparateConnection() returns false.
* The set value is ignored if SequencingControl has been obtained not from ServerSession.
* By default is 2.
* @see org.eclipse.persistence.sessions.server.ConnectionPool
* @see org.eclipse.persistence.sessions.server.ServerSession
*/
void setMinPoolSize(int size);
/**
* PUBLIC:
* Returns a maximum number of connections in sequencing connection pool
* @see org.eclipse.persistence.sessions.server.ConnectionPool
* @see org.eclipse.persistence.sessions.server.ServerSession
*/
int getMaxPoolSize();
/**
* PUBLIC:
* Sets a maximum number of connections in sequencing connection pool
* The set value is ignored if shouldUseSeparateConnection() returns false.
* The set value is ignored if SequencingControl has been obtained not from ServerSession.
* By default is 2.
* @see org.eclipse.persistence.sessions.server.ConnectionPool
* @see org.eclipse.persistence.sessions.server.ServerSession
*/
void setMaxPoolSize(int size);
/**
* PUBLIC:
* Sets a initial number of connections in sequencing connection pool
* The set value is ignored if shouldUseSeparateConnection() returns false.
* The set value is ignored if SequencingControl has been obtained not from ServerSession.
* By default is 1.
* @see org.eclipse.persistence.sessions.server.ConnectionPool
* @see org.eclipse.persistence.sessions.server.ServerSession
*/
void setInitialPoolSize(int size);
/**
* ADVANCED:
* Removes all preallocated sequencing objects.
* Ignored if getSequencingValueGenarationPolicy().shouldUsePreallocation() returns false.
* This method is called internally after Sequencing object is destructed.
* @see Sequence
*/
void initializePreallocated();
/**
* ADVANCED:
* Removes all preallocated sequencing objects for the given sequence name.
* Ignored if getSequencingValueGenarationPolicy().shouldUsePreallocation() returns false.
* @see Sequence
*/
void initializePreallocated(String seqName);
}
|
