01: /*
02: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
03: */
04: package javax.jcr.lock;
05:
06: import javax.jcr.Node;
07: import javax.jcr.RepositoryException;
08:
09: /**
10: * Represents a lock placed on an item.
11: *
12: */
13: public interface Lock {
14:
15: /**
16: * Returns the user ID of the user who owns this lock. This is the value of the
17: * <code>jcr:lockOwner</code> property of the lock-holding node. It is also the
18: * value returned by <code>Session.getUserID</code> at the time that the lock was
19: * placed. The lock owner's identity is only provided for informational purposes.
20: * It does not govern who can perform an unlock or make changes to the locked nodes;
21: * that depends entirely upon who the token holder is.
22: * @return a user ID.
23: */
24: public String getLockOwner();
25:
26: /**
27: * Returns <code>true</code> if this is a deep lock; <code>false</code> otherwise.
28: *
29: * @return a boolean
30: */
31: public boolean isDeep();
32:
33: /**
34: * Returns the lock holding node. Note that <code>N.getLock().getNode()</code>
35: * (where <code>N</code> is a locked node) will only return <code>N</code>
36: * if <code>N</code> is the lock holder. If <code>N</code> is in the subtree
37: * of the lock holder, <code>H</code>, then this call will return <code>H</code>.
38: *
39: * @return an <code>Node</code>.
40: */
41: public Node getNode();
42:
43: /**
44: * May return the lock token for this lock. If this lock is open-scoped and
45: * the current session holds the lock token for this lock, then this method
46: * will return that lock token. Otherwise this method will return
47: * <code>null</code>.
48: *
49: * @return a <code>String</code>.
50: */
51: public String getLockToken();
52:
53: /**
54: * Returns true if this <code>Lock</code> object represents a lock that is currently in effect.
55: * If this lock has been unlocked either explicitly or due to an implementation-specific limitation
56: * (like a timeout) then it returns <code>false</code>. Note that this method is intended for
57: * those cases where one is holding a <code>Lock</code> Java object and wants to find out
58: * whether the lock (the JCR-level entity that is attached to the lockable node) that this
59: * object originally represented still exists. For example, a timeout or explicit
60: * <code>unlock</code> will remove a lock from a node but the <code>Lock</code>
61: * Java object corresponding to that lock may still exist, and in that case its
62: * <code>isLive</code> method will return <code>false</code>.
63: * @return a <code>boolean</code>.
64: * @throws RepositoryException if an error occurs.
65: */
66: public boolean isLive() throws RepositoryException;
67:
68: /**
69: * Returns <code>true</code> if this is a session-scoped lock and the scope is bound to
70: * the current session. Returns <code>false</code> if this is an open-scoped lock or is
71: * session-scoped but the scope is bound to another session.
72: *
73: * @return a <code>boolean</code>.
74: */
75: public boolean isSessionScoped();
76:
77: /**
78: * Returns <code>true</code> if the current session is the owner of this
79: * lock, either because it is session-scoped and bound to this session or
80: * open-scoped and this session currently holds the token for this lock.
81: * Returns <code>false</code> otherwise.
82: *
83: * @return a <code>boolean</code>.
84: * @since JCR 2.0
85: */
86: public boolean isLockOwningSession();
87:
88: /**
89: * If this lock's time-to-live is governed by a timer, this method resets that timer so that the
90: * lock does not timeout and expire. If this lock's time-to-live is not governed by a timer,
91: * then this method has no effect.
92: * <p/>
93: * A <code>LockException</code> is thrown if this <code>Session</code> does not hold the correct lock token for this lock.
94: * @throws LockException if this <code>Session</code> does not hold the correct lock token for this lock.
95: * @throws RepositoryException if another error occurs.
96: */
97: public void refresh() throws LockException, RepositoryException;
98: }
|