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
|
/*
* Copyright 2006 Amazon Technologies, Inc. or its affiliates.
* Amazon, Amazon.com and Carbonado are trademarks or registered trademarks
* of Amazon Technologies, Inc. or its affiliates. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.amazon.carbonado;
import java.lang.annotation.*;
/**
* Designates a {@link Storable} property as being the authoritative version
* number for the entire Storable instance. Only one property can have this
* designation.
*
* <p>Support for the version property falls into three categories. A
* repository may manage the version; it may respect the version; or it may
* merely check the version.
*
* <p><b>Manage</b>: Each storable with a version property must have one and
* only one repository which is responsible for managing the version property.
* That repository takes responsibility for establishing the version on insert,
* and for auto-incrementing it on update. Under no circumstances should the
* version property be incremented manually; this can result in a false
* optimistic lock exception, or worse may allow the persistent record to
* become corrupted. Prior to incrementing, these repositories will verify
* that the version exactly matches the version of the current record, throwing
* an {@link OptimisticLockException} otherwise. The JDBC repository is the
* canonical example of this sort of repository.
*
* <p><b>Respect</b>: Repositories which respect the version use the version to
* guarantee that updates are idempotent -- that is, that an update is applied
* once and only once. These repositories will check that the version property
* is strictly greater than the version of the current record, and will
* (silently) ignore changes which fail this check.
*
* <p><b>Check</b>: Philosophically, a version property can be considered part
* of the identity of the storable. That is, if the storable has a version
* property, it cannot be considered fully specified unless that property is
* specified. Thus, the minimal required support for all repositories is to
* check that the version is specified on update. All repositories -- even
* those which neither check nor manage the version -- will throw an {@link
* IllegalStateException} if the version property is not set before update.
*
* <p>The actual type of the version property can be anything, but some
* repositories might only support integers. For maximum portability, version
* properties should be a regular 32-bit int.
*
* <p>Example:<pre>
* public interface UserInfo extends Storable {
* <b>@Version</b>
* int getRecordVersionNumber();
*
* ...
* }
* </pre>
*
* @author Brian S O'Neill
* @author Don Schneider
* @see OptimisticLockException
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD})
public @interface Version {
}
|
