001/*
002 * (C) Copyright 2015 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 *     Florent Guillaume
018 */
019package org.nuxeo.ecm.core.blob;
020
021import java.util.Collection;
022import java.util.Map;
023import java.util.Set;
024
025import org.nuxeo.ecm.core.api.Blob;
026import org.nuxeo.ecm.core.model.Document;
027
028/**
029 * Interface for a dispatcher of blobs to different blob providers according to metadata.
030 *
031 * @since 7.3
032 */
033public interface BlobDispatcher {
034
035    static final class BlobDispatch {
036        public final String providerId;
037
038        public final boolean addPrefix;
039
040        public BlobDispatch(String providerId, boolean addPrefix) {
041            this.providerId = providerId;
042            this.addPrefix = addPrefix;
043        }
044    }
045
046    /**
047     * Initializes this blob dispatcher.
048     */
049    void initialize(Map<String, String> properties);
050
051    /**
052     * Gets the provider ids to which this dispatcher can dispatch.
053     * <p>
054     * Blobs already having a provider id not listed here won't be touched on write.
055     *
056     * @return a collection containing the provider ids
057     */
058    Collection<String> getBlobProviderIds();
059
060    /**
061     * Decides which {@link BlobProvider} to use to read a blob from the given repository if no prefix is specified in
062     * the blob key.
063     *
064     * @param repositoryName the repository name
065     * @return the blob provider id
066     */
067    String getBlobProvider(String repositoryName);
068
069    /**
070     * Decides which {@link BlobProvider} to use to write the given blob, and whether the provider id should be added as
071     * prefix to the managed blob key.
072     *
073     * @param doc the document containing the blob
074     * @param blob the blob
075     * @return the blob provider id and whether it should be added as prefix
076     * @deprecated since 9.1, use {@link #getBlobProvider(Document, Blob, String)} instead
077     */
078    @Deprecated
079    default BlobDispatch getBlobProvider(Document doc, Blob blob) {
080        return getBlobProvider(doc, blob, null);
081    }
082
083    /**
084     * Decides which {@link BlobProvider} to use to write the given blob, and whether the provider id should be added as
085     * prefix to the managed blob key.
086     *
087     * @param doc the document containing the blob
088     * @param blob the blob
089     * @param xpath the xpath of the blob in the document
090     * @return the blob provider id and whether it should be added as prefix
091     * @since 9.1
092     */
093    BlobDispatch getBlobProvider(Document doc, Blob blob, String xpath);
094
095    /**
096     * Notifies the blob dispatcher that a set of xpaths have changed on a document.
097     *
098     * @param doc the document
099     * @param xpaths the set of changed xpaths
100     * @since 7.3
101     */
102    void notifyChanges(Document doc, Set<String> xpaths);
103
104}