001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (https://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software, please see the
018 * company website: https://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: https://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.ade.contenteditor.shared.rpc;
029
030import org.opencms.acacia.shared.CmsEntity;
031import org.opencms.acacia.shared.CmsValidationResult;
032import org.opencms.ade.contenteditor.shared.CmsContentAugmentationDetails;
033import org.opencms.ade.contenteditor.shared.CmsContentDefinition;
034import org.opencms.ade.contenteditor.shared.CmsEditHandlerData;
035import org.opencms.ade.contenteditor.shared.CmsSaveResult;
036import org.opencms.gwt.CmsRpcException;
037import org.opencms.util.CmsUUID;
038
039import java.util.Collection;
040import java.util.List;
041import java.util.Map;
042
043/**
044 * The content editor service interface.<p>
045 */
046public interface I_CmsContentService extends org.opencms.acacia.shared.rpc.I_CmsContentService {
047
048    /** The content definition dictionary name. */
049    String DICT_CONTENT_DEFINITION = "com_alkacon_acacia_shared_ContentDefinition";
050
051    /** The back-link parameter. */
052    String PARAM_BACKLINK = "backlink";
053
054    /**
055     * Tries to abort a content augmentation job with a given id.
056     *
057     * @param jobId the job ID
058     * @throws CmsRpcException if something goes wrong
059     */
060    public void abortAugmentationJob(CmsUUID jobId) throws CmsRpcException;
061
062    /**
063     * Gets the status (and potentially results) from an augmentation job.
064     * @param jobId the id of the augmentation job
065     *
066     * @return the status and possibly results of the content augmentation
067     * @throws CmsRpcException if something goes wrong
068     */
069    public CmsContentAugmentationDetails getAugmentationProgress(CmsUUID jobId) throws CmsRpcException;
070
071    /**
072     * Sends the edited data back to the server and starts a content augmentation.
073     *
074     * @param entityId the entity id
075     * @param clientId the client id, if available
076     * @param editedEntity the edited entity
077     * @param deletedEntities the deleted entities
078     * @param skipPaths the paths to skip for locale synchronization
079     * @return the id of the content augmentation job
080     *
081     * @throws CmsRpcException in case anything goes wrong
082     */
083    public CmsUUID startAugmentationJob(
084        String entityId,
085        String clientId,
086        CmsEntity editedEntity,
087        List<String> deletedEntities,
088        Collection<String> skipPaths,
089        String augmentationType,
090        Map<String, String> params)
091    throws CmsRpcException;
092
093    /**
094     * Calls the editor change handlers.<p>
095     *
096     * @param entityId the edited entity id
097     * @param editedLocaleEntity the edited entity
098     * @param skipPaths the locale synchronization value paths to skip
099     * @param changedScopes the changed content value paths
100     *
101     * @return the changed content
102     *
103     * @throws CmsRpcException in case anything goes wrong
104     */
105    CmsContentDefinition callEditorChangeHandlers(
106        String entityId,
107        CmsEntity editedLocaleEntity,
108        Collection<String> skipPaths,
109        Collection<String> changedScopes)
110    throws CmsRpcException;
111
112    /**
113     * Copies the given source locale to the target locales.<p>
114     *
115     * @param locales the target locales
116     * @param sourceLocale the source locale
117     *
118     * @throws CmsRpcException if something goes wrong
119     */
120    void copyLocale(Collection<String> locales, CmsEntity sourceLocale) throws CmsRpcException;
121
122    /**
123     * Loads the content definition for a given entity.<p>
124     *
125     * @param entityId the entity id/URI
126     * @param clientId the container element client id if available
127     * @param editedLocaleEntity the edited locale entity
128     * @param skipPaths the paths to skip during locale synchronization
129     * @param settingPresets the presets for container element settings
130     *
131     * @return the content definition
132     *
133     * @throws Exception if something goes wrong processing the request
134     */
135    CmsContentDefinition loadDefinition(
136        String entityId,
137        String clientId,
138        CmsEntity editedLocaleEntity,
139        Collection<String> skipPaths,
140        Map<String, String> settingPresets)
141    throws Exception;
142
143    /**
144     * Loads the content definition for a given entity.<p>
145     *
146     * @param entityId the entity id/URI
147     * @param clientId the container element client id if available
148     * @param newLink the new link
149     * @param modelFileId  the optional model file id
150     * @param editContext the container page currently being edited (may be null)
151     * @param mainLocale the main language to copy in case the element language node does not exist yet
152     * @param mode the content creation mode
153     * @param postCreateHandler the post-create handler class name
154     * @param editHandlerData the edit handler data, if an edit handler is used for creating a new element; null otherwise
155     * @param settingPresets the presets for container element settings
156     * @param editorStylesheet the path of the editor style sheet (may be null)
157     *
158     * @return the content definition
159     *
160     * @throws CmsRpcException if something goes wrong processing the request
161     */
162    CmsContentDefinition loadInitialDefinition(
163        String entityId,
164        String clientId,
165        String newLink,
166        CmsUUID modelFileId,
167        String editContext,
168        String mainLocale,
169        String mode,
170        String postCreateHandler,
171        CmsEditHandlerData editHandlerData,
172        Map<String, String> settingPresets,
173        String editorStylesheet)
174    throws CmsRpcException;
175
176    /**
177     * Loads new entity definition.<p>
178     * This will load the entity representation of a new locale node.<p>
179     *
180     * @param entityId the entity id/URI
181     * @param clientId the container element client id if available
182     * @param editedLocaleEntity the edited locale entity
183     * @param skipPaths the paths to skip during locale synchronization
184     * @param settingPresets the presets for container element settings
185     *
186     * @return the content definition
187     *
188     * @throws CmsRpcException if something goes wrong processing the request
189     */
190    CmsContentDefinition loadNewDefinition(
191        String entityId,
192        String clientId,
193        CmsEntity editedLocaleEntity,
194        Collection<String> skipPaths,
195        Map<String, String> settingPresets)
196    throws CmsRpcException;
197
198    /**
199     * Returns the content definition of the resource requested through parameter 'resource'.<p>
200     *
201     * @return the content definition
202     *
203     * @throws CmsRpcException if something goes wrong
204     */
205    CmsContentDefinition prefetch() throws CmsRpcException;
206
207    /**
208     * Saves and deletes the given entities. Returns the editor save result information.<p>
209     *
210     * @param lastEditedEntity the last edited entity
211     * @param clientId the container element client id if available
212     * @param deletedEntities the entity id's to delete
213     * @param skipPaths the paths to skip during locale synchronization
214     * @param lastEditedLocale the last edited locale
215     * @param clearOnSuccess  <code>true</code> to unlock resource after saving
216     * @param failOnWarnings <code>true</code> to prevent saving when there are validation warnings
217     *
218     * @return the editor save result information
219     *
220     * @throws CmsRpcException if something goes wrong processing the request
221     */
222    CmsSaveResult saveAndDeleteEntities(
223        CmsEntity lastEditedEntity,
224        String clientId,
225        List<String> deletedEntities,
226        Collection<String> skipPaths,
227        String lastEditedLocale,
228        boolean clearOnSuccess,
229        boolean failOnWarnings)
230    throws CmsRpcException;
231
232    /**
233     * Saves a value in an existing XML content.<p>
234     *
235     * @param contentId the structure id of the content
236     * @param contentPath the xpath of the value to set
237     * @param locale the locale in which to set the value
238     * @param value the value to set
239     *
240     * @return not used
241     * @throws CmsRpcException if something goes wrong
242     */
243    String saveValue(String contentId, String contentPath, String locale, String value) throws CmsRpcException;
244
245    /**
246     * Validates the edited XML content, taking all current changes into account. Returns the validation result.<p>
247     *
248     * @param lastEditedEntity the last edited entity
249     * @param clientId the container element client id if available
250     * @param deletedEntities the entity id's to delete
251     * @param skipPaths the paths to skip during locale synchronization
252     * @param lastEditedLocale the last edited locale
253     *
254     * @return the validatoin result
255     *
256     * @throws CmsRpcException if something goes wrong processing the request
257     */
258    CmsValidationResult validateEntities(
259        CmsEntity lastEditedEntity,
260        String clientId,
261        List<String> deletedEntities,
262        Collection<String> skipPaths,
263        String lastEditedLocale)
264    throws CmsRpcException;
265}