/*
 * Copyright (c) 2008-2013, Hazelcast, Inc. 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.hazelcast.map;

import java.io.Serializable;
import java.util.Map;

/**
 * An EntryProcessor passes you a {@link java.util.Map.Entry}. At the time you receive it
 * the entry is locked and not released until the EntryProcessor completes.
 * This obviates the need to explicitly lock as would be required with a {@link java.util.concurrent.ExecutorService}.
 * <p/>
 * Performance can be very high as the data is not moved off the Member partition. This avoids network cost and, if
 * the storage format is {@link com.hazelcast.config.InMemoryFormat#OBJECT} then there is no de-serialization or serialization
 * cost.
 * <p/>
 * EntryProcessors execute on the partition thread in a member. Multiple operations on the same partition are queued.
 * <p/>
 * While executing partition migrations are not allowed. Any migrations are queued on the partition thread.
 * <p/>
 * An EntryProcessor may not be re-entrant i.e. it may not access the same {@link Map}. Limitation: you can only access
 * data on the same partition.
 *
 * @param <K>
 * @param <V>
 */
public interface EntryProcessor<K, V> extends Serializable {

    /**
     * Process the entry without worrying about concurrency.
     * <p/>
     *
     * @param entry entry to be processed
     * @return result of the process
     */
    Object process(Map.Entry<K, V> entry);

    /**
     * Get the entry processor to be applied to backup entries.
     * <p/>
     *
     * @return back up processor
     */
    EntryBackupProcessor<K, V> getBackupProcessor();
}

@@ -1656,183 +1656,1313 @@
 .%0A *
-%0A * @param %3CK%3E%0A * @param %3CV%3E%0A */%0Apublic interface EntryProcessor%3CK, V%3E extends Serializable %7B%0A%0A    /**%0A     * Process the entry without worrying about concurrency.%0A     * %3Cp/%3E
+ %3Cp/%3E%0A * Note that to modify an entry by using EntryProcessors you should explicitly call%0A * %7B@link java.util.Map.Entry#setValue%7D method of %7B@link java.util.Map.Entry%7D such as:%0A * %3Cp/%3E%0A * %3Cpre%3E%0A * %3Ccode%3E%0A * %7B@literal@%7DOverride%0A *     public Object process(Map.Entry entry) %7B%0A *        Value value = entry.getValue();%0A *        // process and modify value%0A *        // ...%0A *        entry.setValue(value);%0A *        return result;%0A *    %7D%0A * %3C/code%3E%0A * %3C/pre%3E%0A * otherwise EntryProcessor does not guarantee to modify the entry.%0A *%0A * @param %3CK%3E%0A * @param %3CV%3E%0A */%0Apublic interface EntryProcessor%3CK, V%3E extends Serializable %7B%0A%0A    /**%0A     * Process the entry without worrying about concurrency.%0A     * %3Cp/%3E%0A     * Note that to modify an entry by using EntryProcessor you should explicitly call%0A     * %7B@link java.util.Map.Entry#setValue%7D method of %7B@link java.util.Map.Entry%7D such as:%0A     * %3Cp/%3E%0A     * %3Cpre%3E%0A     * %3Ccode%3E%0A     * %7B@literal@%7DOverride%0A     *        public Object process(Map.Entry entry) %7B%0A     *          Value value = entry.getValue();%0A     *          // process and modify value%0A     *          // ...%0A     *          entry.setValue(value);%0A     *          return result;%0A     *        %7D%0A     * %3C/code%3E%0A     * %3C/pre%3E%0A     * otherwise EntryProcessor does not guarantee to modify the entry.
 %0A   

add example code which shows the importance of setValue usage to javadoc