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