/* ******************************************************************************
 * Copyright (c) 2006-2016 XMind Ltd. and others.
 * 
 * This file is a part of XMind 3. XMind releases 3 and
 * above are dual-licensed under the Eclipse Public License (EPL),
 * which is available at http://www.eclipse.org/legal/epl-v10.html
 * and the GNU Lesser General Public License (LGPL), 
 * which is available at http://www.gnu.org/licenses/lgpl.html
 * See http://www.xmind.net/license.html for details.
 * 
 * Contributors:
 *     XMind Ltd. - initial API and implementation
 *******************************************************************************/
/**
 * 
 */
package org.xmind.core;

import java.io.IOException;
import java.io.InputStream;

import org.xmind.core.io.ByteArrayStorage;
import org.xmind.core.io.IInputSource;
import org.xmind.core.io.IStorage;
import org.xmind.core.util.IProgressReporter;

/**
 * A deserializer is responsible for parsing binary data into a workbook.
 * Workbooks loaded by this deserializer can be later saved via
 * {@link ISerializer} objects of the same format version.
 * 
 * <p>
 * Instances of this interface can be retrieved via
 * <code>Core.getSerializationProvider().newDeserializer()</code>. <b>NOTE</b>
 * that clients are allowed to use one deserializer instance to load
 * <em>one</em> workbook from <em>one</em> location for only <em>once</em>, and
 * repeated usage of a single deserializer instance may result in unexpected
 * behaviors. Also note that all methods of this interface may NOT be
 * thread-safe.
 * </p>
 * 
 * @author Frank Shaka
 * @since 3.6.50
 */
public interface IDeserializer extends ISerializingBase {

    IManifest getManifest();

    void deserializeManifest(IProgressReporter reporter)
            throws IOException, CoreException, IllegalStateException;

    /**
     * Returns the deserialized workbook.
     * 
     * @return the deserialized workbook, or <code>null</code> if no workbook is
     *         successfully deserialized
     */
    IWorkbook getWorkbook();

    /**
     * Deserializes binary data from the given input source (set via
     * {@link #setInputSource(IInputSource)},
     * {@link #setInputStream(InputStream)}, or
     * {@link #setWorkbookStorageAsInputSource()}) into a workbook, storing its
     * file entries in the specified storage (set via
     * {@link #setWorkbookStorage(IStorage)} or, if not set, a new
     * {@link ByteArrayStorage} created automatically). The deserialized
     * workbook can be retrieved via {@link #getWorkbook()} after the
     * deserialization is done. The progress during the deserialization is
     * reported via the given progress reporter.
     * 
     * @param reporter
     *            an {@link IProgressReporter} object to receive progress
     *            information and indicate user cancellation requests, or
     *            <code>null</code> if the progress is not significant and
     *            cancellation is not required
     * @throws IOException
     *             if any I/O error occurs
     * @throws CoreException
     *             <ul>
     *             <li><code>Core.ERROR_CANCELLATION</code> - if the operation
     *             is canceled</li>
     *             <li><code>Core.ERROR_WRONG_PASSWORD</code> - if the workbook
     *             is encrypted and the decryption operation failed</li>
     *             <li>(TODO add more error codes)</li>
     *             </ul>
     * @throws IllegalStateException
     *             if either input source or workbook storage is not set
     *             properly
     */
    void deserialize(IProgressReporter reporter)
            throws IOException, CoreException, IllegalStateException;

    /**
     * Sets the storage with read-write random-access abilities to store
     * contents of file entries for the deserialized workbook. This storage will
     * be kept and held by the deserialized workbook after deserialization is
     * over. If no storage is set, a new empty in-memory
     * {@link ByteArrayStorage} will be automatically created and used.
     * 
     * @param storage
     *            the {@link IStorage} to use
     * @throws IllegalArgumentException
     *             if the storage is <code>null</code>
     */
    void setWorkbookStorage(IStorage storage);

    /**
     * Returns the storage set via {@link #setWorkbookStorage(IStorage)}.
     * 
     * @return the storage set previously, or <code>null</code> if not set yet
     */
    IStorage getWorkbookStorage();

    /**
     * Sets the input source from which the content of the deserialized workbook
     * will be loaded.
     * 
     * @param source
     *            the {@link IInputSource}
     * @throws IllegalArgumentException
     *             if the source is <code>null</code>
     */
    void setInputSource(IInputSource source);

    /**
     * Sets the input stream as the input source from which the content of the
     * deserialized workbook will be loaded.
     * 
     * <p>
     * NOTE: The deserializer may not close the given stream after usage. The
     * client should close it on its own.
     * </p>
     * 
     * @param stream
     *            the source {@link InputStream}
     * @throws IllegalArgumentException
     *             if the stream is <code>null</code>
     */
    void setInputStream(InputStream stream);

    /**
     * Sets the output target to be the input source of the storage set via
     * {@link #setWorkbookStorage(IStorage)}. Calling this method will remove
     * any input source set previously.
     * 
     * <p>
     * This special setting indicates some special behaviors, e.g. no file
     * entries will be copied to save time.
     * </p>
     */
    void setWorkbookStorageAsInputSource();

    /**
     * Tests whether an input source is properly set via
     * {@link #setInputSource(IInputSource)},
     * {@link #setInputStream(InputStream)} or
     * {@link #setWorkbookStorageAsInputSource()}.
     * 
     * @return <code>true</code> if the input source is set, or
     *         <code>false</code> otherwise
     */
    boolean hasInputSource();

}