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