001/*
002 * (C) Copyright 2014 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 *     vpasquier <vpasquier@nuxeo.com>
018 */
019package org.nuxeo.binary.metadata.api;
020
021import java.util.List;
022import java.util.Map;
023
024import org.nuxeo.binary.metadata.internals.MetadataMappingDescriptor;
025import org.nuxeo.ecm.core.api.Blob;
026import org.nuxeo.ecm.core.api.DocumentModel;
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, Object> 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, Object> 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     * <p>
122     * The document is not saved in the session, it's up to the caller to deal with this.
123     *
124     * @param doc Nuxeo Document which metadata are written.
125     */
126    public void writeMetadata(DocumentModel doc);
127
128    /**
129     * Apply metadata mapping and override document properties according to the contribution.
130     * <p>
131     * The document is not saved in the session, it's up to the caller to deal with this.
132     *
133     * @param doc The input document.
134     * @param mappingDescriptorId The metadata mapping to apply on the document.
135     */
136    public void writeMetadata(DocumentModel doc, String mappingDescriptorId);
137
138    /**
139     * Handle document and blob updates according to following rules in an event context: - Define if rule should be
140     * executed in async or sync mode. - If Blob dirty and document metadata dirty, write metadata from doc to Blob. -
141     * If Blob dirty and document metadata not dirty, write metadata from Blob to doc. - If Blob not dirty and document
142     * metadata dirty, write metadata from doc to Blob.
143     * <p>
144     * The document is not saved in the session, it's up to the caller to deal with this.
145     */
146    void handleUpdate(List<MetadataMappingDescriptor> syncMappingDescriptors, DocumentModel doc);
147
148    /**
149     * Handle document and blob updates according to following rules in an event context: - Define if rule should be
150     * executed in async or sync mode. - If Blob dirty and document metadata dirty, write metadata from doc to Blob. -
151     * If Blob dirty and document metadata not dirty, write metadata from Blob to doc. - If Blob not dirty and document
152     * metadata dirty, write metadata from doc to Blob.
153     * <p>
154     * The document is not saved in the session, it's up to the caller to deal with this.
155     */
156    void handleSyncUpdate(DocumentModel doc);
157
158}