/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 org.apache.commons.configuration2.sync;

 Definition of an interface for objects that can be associated with a Synchronizer. 
 This interface defines methods for querying and setting the Synchronizer. In addition, it is possible to lock the object for a certain operation. This is useful if some complex operations are to be performed on the SynchronizerSupport object in an atomic way. 
 Note that the actual effect of these methods depends on the concrete Synchronizer implementation in use! If only a dummy Synchronizer is involved (which is appropriate if objects are only accessed by a single thread), locking an object does not really prohibit concurrent access. 
Since:
2.0/**
 * <p>
 * Definition of an interface for objects that can be associated with a
 * {@link Synchronizer}.
 * </p>
 * <p>
 * This interface defines methods for querying and setting the
 * {@code Synchronizer}. In addition, it is possible to lock the object for a
 * certain operation. This is useful if some complex operations are to be
 * performed on the {@code SynchronizerSupport} object in an atomic way.
 * </p>
 * <p>
 * Note that the actual effect of these methods depends on the concrete
 * {@code Synchronizer} implementation in use! If only a dummy
 * {@code Synchronizer} is involved (which is appropriate if objects are only
 * accessed by a single thread), locking an object does not really prohibit
 * concurrent access.
 * </p>
 *
 * @since 2.0
 */
public interface SynchronizerSupport
{
    
Returns the Synchronizer used by this object. An implementation must not return null. If no Synchronizer has been set so far, a meaningful default Synchronizer has to be returned. 
Returns:
the Synchronizer used by this object/**
     * Returns the {@code Synchronizer} used by this object. An implementation
     * must not return <b>null</b>. If no {@code Synchronizer} has been set so
     * far, a meaningful default {@code Synchronizer} has to be returned.
     *
     * @return the {@code Synchronizer} used by this object
     */
    Synchronizer getSynchronizer();

    
Sets the Synchronizer to be used by this object. Calling this method and setting an appropriate Synchronizer determines whether this object can be accessed in a thread-safe way or not. The argument may be null; in this case an implementation should switch to a default Synchronizer. 
Params:
sync – the Synchronizer for this object/**
     * Sets the {@code Synchronizer} to be used by this object. Calling this
     * method and setting an appropriate {@code Synchronizer} determines whether
     * this object can be accessed in a thread-safe way or not. The argument may
     * be <b>null</b>; in this case an implementation should switch to a default
     * {@code Synchronizer}.
     *
     * @param sync the {@code Synchronizer} for this object
     */
    void setSynchronizer(Synchronizer sync);

    
Locks this object for the specified mode. This call may block until this object is released from other lock operations. When it returns the caller can access the object in a way compatible to the specified LockMode. When done the unlock() must be called with the same LockMode argument. In practice, a try-finally
construct should be used as in the following example:
SynchronizerSupport syncSupport = ...;
syncSupport.lock(LockMode.READ);
try
{
    // read access to syncSupport
}
finally
{
    syncSupport.unlock(LockMode.READ);
}

Note: Always use this method for obtaining a lock rather than accessing the object's Synchronizer directly. An implementation may perform additional actions which are not executed when only interacting with the Synchronizer. 
Params:
mode – the LockMode/**
     * Locks this object for the specified mode. This call may block until this
     * object is released from other lock operations. When it returns the caller
     * can access the object in a way compatible to the specified
     * {@code LockMode}. When done the {@code unlock()} must be called with the
     * same {@code LockMode} argument. In practice, a <b>try</b>-<b>finally</b>
     * construct should be used as in the following example:
     *
     * <pre>
     * SynchronizerSupport syncSupport = ...;
     * syncSupport.lock(LockMode.READ);
     * try
     * {
     *     // read access to syncSupport
     * }
     * finally
     * {
     *     syncSupport.unlock(LockMode.READ);
     * }
     * </pre>
     *
     * <em>Note:</em> Always use this method for obtaining a lock rather than
     * accessing the object's {@link Synchronizer} directly. An implementation
     * may perform additional actions which are not executed when only
     * interacting with the {@code Synchronizer}.
     *
     * @param mode the {@code LockMode}
     */
    void lock(LockMode mode);

    
Releases a lock of this object that was obtained using the lock(LockMode) method. This method must always be called pair-wise with lock(). The argument must match to the one passed to the corresponding lock() call; otherwise, the behavior of the Synchronizer is unspecified. 
Params:
mode – the LockMode/**
     * Releases a lock of this object that was obtained using the
     * {@link #lock(LockMode)} method. This method must always be called
     * pair-wise with {@code lock()}. The argument must match to the one passed
     * to the corresponding {@code lock()} call; otherwise, the behavior of the
     * {@link Synchronizer} is unspecified.
     *
     * @param mode the {@code LockMode}
     */
    void unlock(LockMode mode);
}