001/*
002 * (C) Copyright 2014 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl-2.1.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     vpasquier <vpasquier@nuxeo.com>
016 */
017package org.nuxeo.binary.metadata.api;
018
019import java.util.List;
020import java.util.Map;
021
022import org.nuxeo.binary.metadata.internals.MetadataMappingDescriptor;
023import org.nuxeo.ecm.core.api.Blob;
024import org.nuxeo.ecm.core.api.CoreSession;
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.event.impl.DocumentEventContext;
027
028/**
029 * Read/Write binary metadata services.
030 *
031 * @since 7.1
032 */
033public interface BinaryMetadataService {
034
035    /**
036     * Read and return metadata from a given binary and a given metadata list with a given processor.
037     *
038     * @param processorName Name of the contributed processor to run.
039     * @param blob Binary which metadata are read.
040     * @param metadataNames Metadata list to extract from the binary.
041     * @param ignorePrefix Since 7.3
042     * @return Extracted metadata.
043     */
044    public Map<String, Object> readMetadata(String processorName, Blob blob, List<String> metadataNames,
045            boolean ignorePrefix);
046
047    /**
048     * Read and return metadata from a given binary and a given metadata list with Nuxeo default processor.
049     *
050     * @param blob Binary which metadata are read.
051     * @param metadataNames Metadata list to extract from the binary.
052     * @param ignorePrefix Since 7.3
053     * @return Extracted metadata.
054     */
055    public Map<String, Object> readMetadata(Blob blob, List<String> metadataNames, boolean ignorePrefix);
056
057    /**
058     * Read and return metadata from a given binary with Nuxeo default processor.
059     *
060     * @param blob Binary which metadata are read.
061     * @param ignorePrefix Since 7.3
062     * @return Extracted metadata.
063     */
064    public Map<String, Object> readMetadata(Blob blob, boolean ignorePrefix);
065
066    /**
067     * Read and return metadata from a given binary with a given processor.
068     *
069     * @param processorName Name of the contributed processor to run.
070     * @param blob Binary which metadata are read.
071     * @param ignorePrefix Since 7.3
072     * @return Extracted metadata.
073     */
074    public Map<String, Object> readMetadata(String processorName, Blob blob, boolean ignorePrefix);
075
076    /**
077     * Write given metadata into a given binary with a given processor.
078     *
079     * @param processorName Name of the contributed processor to run.
080     * @param blob Binary which metadata are written.
081     * @param metadata Injected metadata.
082     * @param ignorePrefix Since 7.3
083     * @return the updated blob, or {@code null} if there was an error (since 7.4)
084     */
085    public Blob writeMetadata(String processorName, Blob blob, Map<String, String> metadata, boolean ignorePrefix);
086
087    /**
088     * Write given metadata into a given binary with a Nuxeo default processor.
089     *
090     * @param blob Binary which metadata are written.
091     * @param metadata Injected metadata.
092     * @param ignorePrefix Since 7.3
093     * @return the updated blob, or {@code null} if there was an error (since 7.4)
094     */
095    public Blob writeMetadata(Blob blob, Map<String, String> metadata, boolean ignorePrefix);
096
097    /**
098     * Write given metadata mapping id into a given binary with a Nuxeo default processor.
099     *
100     * @param processorName Name of the contributed processor to run.
101     * @param blob Binary which metadata are written.
102     * @param mappingDescriptorId The metadata mapping to apply on the document.
103     * @param doc Document from properties will be read.
104     * @return the updated blob, or {@code null} if there was an error (since 7.4)
105     */
106    public Blob writeMetadata(String processorName, Blob blob, String mappingDescriptorId, DocumentModel doc);
107
108    /**
109     * Write given metadata mapping id into a given binary with a Nuxeo default processor.
110     *
111     * @param blob Binary which metadata are written.
112     * @param mappingDescriptorId The metadata mapping to apply on the document.
113     * @param doc Document from properties will be read.
114     * @return the updated blob, or {@code null} if there was an error (since 7.4)
115     */
116    public Blob writeMetadata(Blob blob, String mappingDescriptorId, DocumentModel doc);
117
118    /**
119     * Write metadata (from a binary) into a given Nuxeo Document according to the metadata mapping and rules
120     * contributions.
121     *
122     * @param doc Nuxeo Document which metadata are written.
123     */
124    public void writeMetadata(DocumentModel doc, CoreSession session);
125
126    /**
127     * Apply metadata mapping and override document properties according to the contribution.
128     *
129     * @param doc The input document.
130     * @param session core session.
131     * @param mappingDescriptorId The metadata mapping to apply on the document.
132     */
133    public void writeMetadata(DocumentModel doc, CoreSession session, String mappingDescriptorId);
134
135    /**
136     * Handle document and blob updates according to following rules in an event context: - Define if rule should be
137     * executed in async or sync mode. - If Blob dirty and document metadata dirty, write metadata from doc to Blob. -
138     * If Blob dirty and document metadata not dirty, write metadata from Blob to doc. - If Blob not dirty and document
139     * metadata dirty, write metadata from doc to Blob.
140     */
141    void handleUpdate(List<MetadataMappingDescriptor> syncMappingDescriptors, DocumentModel doc,
142            DocumentEventContext docCtx);
143
144    /**
145     * Handle document and blob updates according to following rules in an event context: - Define if rule should be
146     * executed in async or sync mode. - If Blob dirty and document metadata dirty, write metadata from doc to Blob. -
147     * If Blob dirty and document metadata not dirty, write metadata from Blob to doc. - If Blob not dirty and document
148     * metadata dirty, write metadata from doc to Blob.
149     */
150    void handleSyncUpdate(DocumentModel doc, DocumentEventContext docCtx);
151
152}