<commit_before>/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package com.xpn.xwiki.store;

import java.util.Date;

import org.xwiki.component.annotation.Role;

import com.xpn.xwiki.XWikiContext;
import com.xpn.xwiki.XWikiException;
import com.xpn.xwiki.doc.XWikiDeletedDocument;
import com.xpn.xwiki.doc.XWikiDocument;

/**
 * Interface for RecycleBin feature (XWIKI-543) store system.
 *
 * @version $Id$
 * @since 1.2M1
 */
@Role
public interface XWikiRecycleBinStoreInterface
{
    /**
     * Save document to recycle bin.
     *
     * @param doc - document to save
     * @param deleter - the user which delete document
     * @param date - date of delete action
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @param context - used while saving
     * @throws XWikiException if error in saving
     */
    void saveToRecycleBin(XWikiDocument doc, String deleter, Date date, XWikiContext context, boolean bTransaction)
        throws XWikiException;

    /**
     * Save document to recycle bin.
     *
     * @param doc - document to save
     * @param deleter - the user which delete document
     * @param date - date of delete action
     * @param batchId - id of the operation that deleted multiple documents at the same time, useful when trying to
     *            revert the operation. {@code null} or empty values are ignored
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @param context - used while saving
     * @throws XWikiException if error in saving
     * @since 9.4RC1
     */
    default void saveToRecycleBin(XWikiDocument doc, String deleter, Date date, String batchId, XWikiContext context,
        boolean bTransaction) throws XWikiException
    {
        // Empty default implementation.
        // XXX: the current signature does not return the saved document index so we can't delegate to the older
        // saveToRecycleBin because we have no way of setting the batchId on the saved document, so we would not be
        // respecting the new method's contract and would only do it's job partially.
    }

    /**
     * @return restored document from recycle bin
     * @param doc - document to restore
     * @param index - what deleted document to restore. see {@link XWikiDeletedDocument#getId()}
     * @param context - used while loading
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @throws XWikiException if error while loading
     * @deprecated since 9.4RC1. The document parameter is useless and gets in the way. Use
     *             {@link #restoreFromRecycleBin(long, XWikiContext, boolean)} instead.
     */
    @Deprecated
    XWikiDocument restoreFromRecycleBin(XWikiDocument doc, long index, XWikiContext context, boolean bTransaction)
        throws XWikiException;

    /**
     * @param index - what deleted document to restore. see {@link XWikiDeletedDocument#getId()}
     * @param context - used while loading
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @return the restored document from recycle bin
     * @throws XWikiException if error while loading
     * @since 9.4RC1
     */
    default XWikiDocument restoreFromRecycleBin(long index, XWikiContext context, boolean bTransaction)
        throws XWikiException
    {
        // XXX: Depending on how an older implementation handled the XWikiDocument argument, it's relatively safer to
        // pass an empty document than null. However, if the document's reference is actually used, the result might be
        // unpredictable.<commit_msg>XWIKI-14244: Clean the recycle bin API to make it more usable XWIKI-13164: Be able to also restore deleted children pages when restoring a parent nested page<commit_after>/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package com.xpn.xwiki.store;

import java.util.Date;

import org.xwiki.component.annotation.Role;

import com.xpn.xwiki.XWikiContext;
import com.xpn.xwiki.XWikiException;
import com.xpn.xwiki.doc.XWikiDeletedDocument;
import com.xpn.xwiki.doc.XWikiDocument;

/**
 * Interface for RecycleBin feature (XWIKI-543) store system.
 *
 * @version $Id$
 * @since 1.2M1
 */
@Role
public interface XWikiRecycleBinStoreInterface
{
    /**
     * Save document to recycle bin.
     *
     * @param doc - document to save
     * @param deleter - the user which delete document
     * @param date - date of delete action
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @param context - used while saving
     * @throws XWikiException if error in saving
     */
    void saveToRecycleBin(XWikiDocument doc, String deleter, Date date, XWikiContext context, boolean bTransaction)
        throws XWikiException;

    /**
     * Save document to recycle bin.
     *
     * @param doc - document to save
     * @param deleter - the user which delete document
     * @param date - date of delete action
     * @param batchId - id of the operation that deleted multiple documents at the same time, useful when trying to
     *            revert the operation. {@code null} or empty values are ignored
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @param context - used while saving
     * @throws XWikiException if error in saving
     * @since 9.4RC1
     */
    default void saveToRecycleBin(XWikiDocument doc, String deleter, Date date, String batchId, XWikiContext context,
        boolean bTransaction) throws XWikiException
    {
        // XXX: The current signature does not return the saved document index so we have no way of setting the batchId
        // to the save document. This means we can`t completely respect the method`s contract, but at least the most
        // important part of the work is done and the document can be individually restored.
        saveToRecycleBin(doc, deleter, date, context, bTransaction);
    }

    /**
     * @return restored document from recycle bin
     * @param doc - document to restore
     * @param index - what deleted document to restore. see {@link XWikiDeletedDocument#getId()}
     * @param context - used while loading
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @throws XWikiException if error while loading
     * @deprecated since 9.4RC1. The document parameter is useless and gets in the way. Use
     *             {@link #restoreFromRecycleBin(long, XWikiContext, boolean)} instead.
     */
    @Deprecated
    XWikiDocument restoreFromRecycleBin(XWikiDocument doc, long index, XWikiContext context, boolean bTransaction)
        throws XWikiException;

    /**
     * @param index - what deleted document to restore. see {@link XWikiDeletedDocument#getId()}
     * @param context - used while loading
     * @param bTransaction - should use old transaction(false) or create new (true)
     * @return the restored document from recycle bin
     * @throws XWikiException if error while loading
     * @since 9.4RC1
     */
    default XWikiDocument restoreFromRecycleBin(long index, XWikiContext context, boolean bTransaction)
        throws XWikiException
    {
        // XXX: Depending on how an older implementation handled the XWikiDocument argument, it's relatively safer to
        // pass an empty document than null. However, if the document's reference is actually used, the result might be
        // unpredictable.
{'fraction_non_alphanumeric': 0.06861138424560254, 'fraction_numerical': 0.007210750573582432, 'mean_word_length': 3.1571298819255222, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4829667', 'n_tokens_mistral': 2448, 'n_tokens_neox': 2382, 'n_words': 1071}