001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package org.apache.openjpa.kernel;
020:
021: import java.util.Collection;
022:
023: import org.apache.openjpa.lib.util.Closeable;
024:
025: /**
026: * Handles obtaining and releasing locks on objects. The lock manager
027: * generally does not have to worry about synchronization, as the context is
028: * responsible for synchronizing the calls it makes to the lock manager.
029: *
030: * @author Marc Prud'hommeaux
031: */
032: public interface LockManager extends Closeable, LockLevels {
033:
034: /**
035: * Set the context this lock manager is associated with.
036: * This will be invoked in the lock manager before any other methods are
037: * called.
038: */
039: public void setContext(StoreContext ctx);
040:
041: /**
042: * Return the lock level of the specified instance, or
043: * {@link LockLevels#LOCK_NONE} if not locked.
044: */
045: public int getLockLevel(OpenJPAStateManager sm);
046:
047: /**
048: * Obtain a lock on the specified object. This method may be called when
049: * a user explicitly locks an object, and is also called automatically
050: * for every object accessed during a transaction. The implementation
051: * must track already-locked objects, and must be optimized to return
052: * quickly when the given object does not need additional locking.
053: * The lock manager might use the state manager's lock object for
054: * bookkeeping information.
055: *
056: * @param sm the object to lock
057: * @param level one of the lock constants defined in {@link LockLevels},
058: * or a custom level
059: * @param timeout the timeout in milliseconds, or a negative number for
060: * no timeout
061: * @param sdata the context information passed from the store manager
062: * to the persistence context, if any; lock managers
063: * specific to a certain back end may be able to take
064: * advantage of this; others should ignore it
065: * @throws org.apache.openjpa.util.LockException if a lock cannot be
066: * obtained in the given number of milliseconds
067: * @see OpenJPAStateManager#setLock
068: */
069: public void lock(OpenJPAStateManager sm, int level, int timeout,
070: Object sdata);
071:
072: /**
073: * Obtain locks on the specified objects.
074: *
075: * @see #lock
076: */
077: public void lockAll(Collection sms, int level, int timeout,
078: Object sdata);
079:
080: /**
081: * Release the lock on the given object. This method will be called
082: * automatically for each state manager with a lock object set on
083: * transaction completion, just before the call to {@link #endTransaction}.
084: * The lock manager should null the state manager's lock object. Note
085: * that some state manager may be garbage collected during a transaction;
086: * thus lock managers cannot rely on this method being called for every
087: * state manager.
088: *
089: * @see OpenJPAStateManager#setLock
090: */
091: public void release(OpenJPAStateManager sm);
092:
093: /**
094: * Notification that a transaction is beginning. Locks are only obtained
095: * within transactions, so an implementation might use this method to
096: * initialize bookkeeping datastructures, etc.
097: */
098: public void beginTransaction();
099:
100: /**
101: * Notification that the current transaction has ended. Clear all
102: * datastructures, release any left over locks, etc.
103: */
104: public void endTransaction();
105:
106: /**
107: * Free any resources.
108: */
109: public void close();
110: }
|