001/*
002 *  Copyright 2016 Anyware Services
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 */
016package org.ametys.plugins.contentio.synchronize;
017
018import java.util.List;
019import java.util.Map;
020import java.util.Set;
021
022import org.slf4j.Logger;
023
024import org.ametys.cms.data.ContentSynchronizationResult;
025import org.ametys.cms.repository.ModifiableContent;
026import org.ametys.core.right.RightAssignmentContext;
027import org.ametys.plugins.contentio.synchronize.search.SCCSearchModelConfiguration;
028import org.ametys.runtime.i18n.I18nizableText;
029
030/**
031 * This interface represents a synchronizable collection of contents
032 *
033 */
034public interface SynchronizableContentsCollection
035{
036    /** The name for the metadata indicating the ids of the collections */
037    public static final String COLLECTION_ID_DATA_NAME = "scc";
038    /** The name of the metadata indicating the date of the last synchronization */
039    public static final String LAST_SYNCHRONIZATION_DATA_NAME = "lastSynchronization";
040    /** The name of the metadata indicating the user that launched the last synchronization */
041    public static final String LAST_SYNCHRONIZATION_USER_DATA_NAME = "lastSynchronizationUser";
042    
043    /** The result map key for number of created contents */
044    public static final String RESULT_NB_CREATED_CONTENTS = "nbCreatedContents";
045    /** The result map key for number of synchronized contents */
046    public static final String RESULT_NB_SYNCHRONIZED_CONTENTS = "nbSynchronizedContents";
047    /** The result map key for number of synchronized contents */
048    public static final String RESULT_NB_NOT_CHANGED_CONTENTS = "nbNotChangedContents";
049    /** The result map key for number of deleted contents */
050    public static final String RESULT_NB_DELETED_CONTENTS = "nbDeletedContents";
051    
052    /**
053     * Get the id of synchronizable collection.
054     * @return the id
055     */
056    String getId();
057    
058    /**
059     * Get the label of synchronizable collection
060     * @return the label
061     */
062    I18nizableText getLabel();
063    
064    /**
065     * Get the type of content handled by this collection
066     * @return the type of content
067     */
068    String getContentType();
069    
070    /**
071     * Get the languages handled by this collection
072     * @return the list of language
073     */
074    List<String> getLanguages();
075    
076    /**
077     * Get the id of controller responsible of synchronization of this collection
078     * @return The id of controller
079     */
080    String getSynchronizeCollectionModelId();
081    
082    /**
083     * Get the untyped values of parameters for controller
084     * @return the untyped values
085     */
086    Map<String, Object> getParameterValues();
087    
088    /**
089     * When returns <code>true</code>, a content created by a previous synchro will be removed if it does not exist anymore during the current synchro.
090     * @return <code>true</code> if a content created by a previous synchro has to be removed if it does not exist anymore during the current synchro.
091     */
092    boolean removalSync();
093    
094    /**
095     * When returns <code>true</code>, the process ignore restrictions on attributes to synchronize it.
096     * @return <code>true</code> to ignore restrictions on synchronization
097     */
098    boolean ignoreRestrictions();
099    
100    /**
101     * Get the name of the workflow to use for the synchronized contents
102     * @return the name of the workflow to use for the synchronized contents
103     */
104    String getWorkflowName();
105    
106    /**
107     * Get the id of the initial action of the workflow
108     * @return The id of the initial action of the workflow
109     */
110    int getInitialActionId();
111    
112    /**
113     * Get the id of the synchronize action of the workflow
114     * @return The id of the synchronize action of the workflow
115     */
116    int getSynchronizeActionId();
117    
118    /**
119     * Get the id of the validate action of the workflow
120     * @return The id of the validate action of the workflow
121     */
122    int getValidateActionId();
123    
124    /**
125     * Get the prefix to use for the creation of contents
126     * @return The prefix to use for the creation of contents
127     */
128    String getContentPrefix();
129    
130    /**
131     * True to validate the contents after import
132     * @return True to validate the contents after import
133     */
134    boolean validateAfterImport();
135    
136    /**
137     * If an exception occurs during synchronization, an error report mail will be sent to those email addresses (separated by new lines)
138     * @return The email addresses to send an error report if an exception occurs during synchronization (separated by new lines)
139     */
140    String getReportMails();
141    
142    /**
143     * Gets the id of the {@link SynchronizingContentOperator} extension to use during synchronization
144     * @return the id of the {@link SynchronizingContentOperator} extension to use during synchronization
145     */
146    String getSynchronizingContentOperator();
147    
148    /**
149     * Get the path of boolean metadata for restricted content.
150     * If true, the content will be visible only for connected users.
151     * @return the path to the metadata. Can be null.
152     */
153    String getRestrictedField();
154    
155    /**
156     * Get the path of metadata holding the unique identifier
157     * @return the path to the metadata. Can be null.
158     */
159    String getIdField();
160    
161    /**
162     * Get the path of tri-state fields (with local and external values)
163     * @param additionalParameters Additional parameters
164     * @return the synchronized fields
165     */
166    Set<String> getLocalAndExternalFields(Map<String, Object> additionalParameters);
167    
168    /**
169     * Get the search UI model for search tool (columns, criterias, url for buttons, etc.)
170     * @return A {@link SCCSearchModelConfiguration}
171     */
172    SCCSearchModelConfiguration getSearchModelConfiguration();
173    
174    /**
175     * True to synchronize only existing contents
176     * @return True to synchronize only existing contents
177     */
178    boolean synchronizeExistingContentsOnly();
179    
180    /**
181     * Empty the collection of its synchronized contents
182     * @param logger The logger
183     */
184    public void empty(Logger logger);
185    
186    /**
187     * Populates contents
188     * @param logger The logger
189     * @return Return the populated contents (imported or synchronized)
190     */
191    public List<ModifiableContent> populate(Logger logger);
192    
193    /**
194     * Import a content from remote values.
195     * @param idValue Id (for import/synchronization) of the content to import
196     * @param additionalParameters Additional parameters
197     * @param logger The logger
198     * @return A list of created contents
199     * @throws Exception if an error occurs.
200     */
201    public List<ModifiableContent> importContent(String idValue, Map<String, Object> additionalParameters, Logger logger) throws Exception;
202    
203    /**
204     * Synchronize a content with remove values.
205     * @param content The content to synchronize
206     * @param logger The logger
207     * @throws Exception if an error occurs.
208     */
209    public void synchronizeContent(ModifiableContent content, Logger logger) throws Exception;
210    
211    /**
212     * Add specific fields to the content.
213     * @param content Content to update
214     * @param additionalParameters Additional parameters
215     * @param logger The logger
216     * @return The synchronization result of the import additional operations
217     */
218    public default ContentSynchronizationResult additionalImportOperations(ModifiableContent content, Map<String, Object> additionalParameters, Logger logger)
219    {
220        return additionalCommonOperations(content, additionalParameters, logger);
221    }
222
223    /**
224     * Add specific fields to the content.
225     * @param content Content to update
226     * @param additionalParameters Additional parameters
227     * @param logger The logger
228     * @return The synchronization result of the synchronize additional operations
229     */
230    public default ContentSynchronizationResult additionalSynchronizeOperations(ModifiableContent content, Map<String, Object> additionalParameters, Logger logger)
231    {
232        return additionalCommonOperations(content, additionalParameters, logger);
233    }
234    
235    /**
236     * Add specific fields to the content during import or synchronization.
237     * @param content Content to update
238     * @param additionalParameters Additional parameters
239     * @param logger The logger
240     * @return The synchronization result of the additional operations
241     */
242    public default ContentSynchronizationResult additionalCommonOperations(ModifiableContent content, Map<String, Object> additionalParameters, Logger logger)
243    {
244        // Do nothing by default
245        return new ContentSynchronizationResult();
246    }
247    
248    /**
249     * Gets the content in the repository
250     * @param lang the language
251     * @param idValue the content name
252     * @return the content in the repository, or null if does not exist
253     */
254    public ModifiableContent getContent(String lang, String idValue);
255    
256    /**
257     * Search the data to import from parameters.
258     * @param searchParameters Parameters for the search
259     * @param offset Begin of the search
260     * @param limit Number of results
261     * @param sort Sort of results (ignored for LDAP results)
262     * @param logger The logger
263     * @return A map of remote values by content
264     */
265    public Map<String, Map<String, Object>> search(Map<String, Object> searchParameters, int offset, int limit, List<Object> sort, Logger logger);
266
267    /**
268     * Method to update the synchronisation informations (collection and value of the ID field).
269     * @param content Content to update
270     * @param syncCode New synchronization code
271     * @param logger The logger
272     * @throws Exception if an error occurs.
273     */
274    public void updateSyncInformations(ModifiableContent content, String syncCode, Logger logger) throws Exception;
275    
276    /**
277     * Return the total number of results for the search.
278     * @param searchParameters Parameters for the search
279     * @param logger The logger
280     * @return The total count
281     */
282    public int getTotalCount(Map<String, Object> searchParameters, Logger logger);
283    
284    /**
285     * Retrieves the result of the synchronization as a map of key / content count containing
286     * <ul>
287     * <li>The number of created contents</li>
288     * <li>The number of synchronized contents</li>
289     * <li>The number of unchanged contents</li>
290     * <li>The number of deleted contents</li>
291     * </ul>
292     * @return the result of the synchronization
293     */
294    public Map<String, Integer> getSynchronizationResult(); 
295    
296    /**
297     * Return true if a {@link RightAssignmentContext} should be automatically generated for the contents of this SCC
298     * @return true to automatically generate a {@link RightAssignmentContext}. Return false if the rights of contents of this SCC are handle by its own {@link RightAssignmentContext}
299     */
300    public default boolean handleRightAssignmentContext()
301    {
302        return true;
303    }
304}