001/*
002 * (C) Copyright 2006 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Nuxeo - initial API and implementation
018 *
019 *
020 * $Id: Plugin.java 4449 2006-10-19 11:51:56Z janguenot $
021 */
022
023package org.nuxeo.ecm.platform.filemanager.service.extension;
024
025import java.io.IOException;
026import java.io.Serializable;
027import java.util.List;
028
029import org.nuxeo.ecm.core.api.Blob;
030import org.nuxeo.ecm.core.api.CoreSession;
031import org.nuxeo.ecm.core.api.DocumentModel;
032import org.nuxeo.ecm.platform.filemanager.api.FileImporterContext;
033import org.nuxeo.ecm.platform.filemanager.service.FileManagerService;
034import org.nuxeo.ecm.platform.types.TypeManager;
035import org.nuxeo.runtime.api.Framework;
036
037/**
038 * FileManagerServiceCommon plugin default interface.
039 * <p>
040 * Responsible for converting given sources to a given type of Document using default.
041 *
042 * @author <a href="mailto:[email protected]">Andreas Kalogeropoulos</a>
043 * @author Anahide Tchertchian
044 */
045public interface FileImporter extends Serializable, Comparable<FileImporter> {
046
047    // XXX: OG: why make plugin serializable?
048
049    /**
050     * Gets the plugin name.
051     *
052     * @return a string holding the plugin name
053     */
054    String getName();
055
056    /**
057     * Returns the document type configured for this {@code FileImporter}, {@code null} if no document type is
058     * configured.
059     *
060     * @since 5.5
061     */
062    String getDocType();
063
064    /**
065     * Sets the document type configured for this importer.
066     * <p>
067     *
068     * @since 5.5
069     */
070    void setDocType(String docType);
071
072    /**
073     * Gets filters.
074     * <p>
075     * The filters are all the mime/type this plugin can deal with.
076     *
077     * @return list of string holding each filters.
078     */
079    List<String> getFilters();
080
081    /**
082     * Sets plugin name.
083     *
084     * @param name a string holding the name
085     */
086    void setName(String name);
087
088    /**
089     * Sets filters.
090     * <p>
091     * The filters are all the mime/types this plugin can deal with.
092     *
093     * @param filters a list of strings representing each filter
094     */
095    void setFilters(List<String> filters);
096
097    /**
098     * Embeds a reference to the holding FileManagerService instance to be able to reuse generic file creation utility
099     * methods in specific plugin implementations.
100     *
101     * @param fileManagerService instance where the Plugin is registered as a contribution
102     * @deprecated since 10.3, use {@link Framework#getService(Class)} instead if needed
103     */
104    @Deprecated
105    void setFileManagerService(FileManagerService fileManagerService);
106
107    /**
108     * Tests whether plugin is suitable for the given mimetype.
109     *
110     * @param mimeType the mimetype to test
111     */
112    boolean matches(String mimeType);
113
114    /**
115     * Creates the document.
116     *
117     * @param documentManager the manager used to create the Document
118     * @param content the content of the File
119     * @param path the path of current document
120     * @param overwrite a boolean deciding whether to create or update if we find a document with the same fileName
121     * @param filename the filename of the File
122     * @deprecated since 10.10. Use {@link #createOrUpdate(FileImporterContext)} instead.
123     */
124    @Deprecated
125    DocumentModel create(CoreSession documentManager, Blob content, String path, boolean overwrite, String filename,
126            TypeManager typeService) throws IOException;
127
128    /**
129     * Returns a created or updated document based on the given {@code context}.
130     *
131     * @see FileImporterContext
132     * @since 10.10
133     */
134    DocumentModel createOrUpdate(FileImporterContext fileImporterContext) throws IOException;
135
136    boolean isEnabled();
137
138    void setEnabled(boolean enabled);
139
140    /**
141     * Returns the plugin order for sorting.
142     */
143    Integer getOrder();
144
145    /**
146     * Sets the plugin order for sorting.
147     */
148    void setOrder(Integer order);
149
150    /**
151     * Returns {@code true} if {@link #createOrUpdate(FileImporterContext)} creates more than one document for the given
152     * blob, {@code false} otherwise.
153     *
154     * @since 10.3
155     */
156    boolean isOneToMany();
157
158}