001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://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: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://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.gwt.shared.rpc;
029
030import org.opencms.db.CmsResourceState;
031import org.opencms.gwt.CmsRpcException;
032import org.opencms.gwt.shared.CmsBroadcastMessage;
033import org.opencms.gwt.shared.CmsCategoryTreeEntry;
034import org.opencms.gwt.shared.CmsContextMenuEntryBean;
035import org.opencms.gwt.shared.CmsCoreData;
036import org.opencms.gwt.shared.CmsCoreData.AdeContext;
037import org.opencms.gwt.shared.CmsCoreData.UserInfo;
038import org.opencms.gwt.shared.CmsResourceCategoryInfo;
039import org.opencms.gwt.shared.CmsReturnLinkInfo;
040import org.opencms.gwt.shared.CmsUserSettingsBean;
041import org.opencms.gwt.shared.CmsValidationQuery;
042import org.opencms.gwt.shared.CmsValidationResult;
043import org.opencms.util.CmsUUID;
044
045import java.util.List;
046import java.util.Map;
047import java.util.Set;
048
049import com.google.gwt.user.client.rpc.RemoteService;
050
051/**
052 * Provides general core services.<p>
053 *
054 * @since 8.0.0
055 *
056 * @see org.opencms.gwt.CmsCoreService
057 * @see org.opencms.gwt.shared.rpc.I_CmsCoreService
058 * @see org.opencms.gwt.shared.rpc.I_CmsCoreServiceAsync
059 */
060public interface I_CmsCoreService extends RemoteService {
061
062    /**
063     * Changes the password of the current user.<p>
064     *
065     * @param oldPassword the old password
066     * @param newPassword the value entered for the new password
067     * @param newPasswordConfirm the value entered for the confirmation of the new password
068     *
069     * @return an error message if an error occurred, or null if the password was successfully changed
070     *
071     * @throws CmsRpcException if something goes wrong
072     */
073    String changePassword(String oldPassword, String newPassword, String newPasswordConfirm) throws CmsRpcException;
074
075    /**
076    * Creates a new UUID.<p>
077    *
078    * @return the created UUID
079    *
080    * @throws CmsRpcException if something goes wrong
081    */
082    CmsUUID createUUID() throws CmsRpcException;
083
084    /**
085     * Returns the latest messages for the current user.<p>
086     *
087     * @return the messages
088     *
089     * @throws CmsRpcException if anything goes wrong
090     */
091    List<CmsBroadcastMessage> getBroadcast() throws CmsRpcException;
092
093    /**
094     * Returns the categories for the given search parameters.<p>
095     *
096     * @param fromCatPath the category path to start with, can be <code>null</code> or empty to use the root
097     * @param includeSubCats if to include all categories, or first level child categories only
098     * @param refVfsPath the reference path (site-relative path according to which the available category repositories are determined),
099     *        can be <code>null</code> to only use the system repository
100     *
101     * @return the resource categories
102     *
103     * @throws CmsRpcException if something goes wrong
104     */
105    List<CmsCategoryTreeEntry> getCategories(String fromCatPath, boolean includeSubCats, String refVfsPath)
106    throws CmsRpcException;
107
108    /**
109     * Returns the categories for the given search parameters.<p>
110     *
111     * @param fromCatPath the category path to start with, can be <code>null</code> or empty to use the root
112     * @param includeSubCats if to include all categories, or first level child categories only
113     * @param refVfsPath the reference path (site-relative path according to which the available category repositories are determined),
114     *        can be <code>null</code> to only use the system repository
115     * @param withRepositories flag, indicating if also the category repositories should be returned as category
116     *
117     * @return the resource categories
118     *
119     * @throws CmsRpcException if something goes wrong
120     */
121    List<CmsCategoryTreeEntry> getCategories(
122        String fromCatPath,
123        boolean includeSubCats,
124        String refVfsPath,
125        boolean withRepositories)
126    throws CmsRpcException;
127
128    /**
129     * Returns the categories for the given reference site-path.<p>
130     *
131     * @param sitePath the reference site-path
132     *
133     * @return the categories for the given reference site-path
134     *
135     * @throws CmsRpcException if something goes wrong
136     */
137    List<CmsCategoryTreeEntry> getCategoriesForSitePath(String sitePath) throws CmsRpcException;
138
139    /**
140     * Returns the category information for the given resource.<p>
141     *
142     * @param structureId the resource structure id
143     *
144     * @return the category information
145     *
146     * @throws CmsRpcException if something goes wrong
147     */
148    CmsResourceCategoryInfo getCategoryInfo(CmsUUID structureId) throws CmsRpcException;
149
150    /**
151     * Returns the context menu entries for the given URI.<p>
152     *
153     * @param structureId the currently requested structure id
154     * @param context the ade context (sitemap or containerpage)
155     *
156     * @return the context menu entries
157     *
158     * @throws CmsRpcException if something goes wrong
159     */
160    List<CmsContextMenuEntryBean> getContextMenuEntries(CmsUUID structureId, AdeContext context) throws CmsRpcException;
161
162    /**
163     * Returns the context menu entries for the given URI.<p>
164     *
165     * @param structureId the currently requested structure id
166     * @param context the ade context (sitemap or containerpage)
167     * @param params additional context information the server side can use to determine menu item availability
168     *
169     * @return the context menu entries
170     *
171     * @throws CmsRpcException if something goes wrong
172     */
173
174    List<CmsContextMenuEntryBean> getContextMenuEntries(
175        CmsUUID structureId,
176        AdeContext context,
177        Map<String, String> params)
178    throws CmsRpcException;
179
180    /**
181     * Given a return code, returns the link to the page which corresponds to the return code.<p>
182     *
183     * @param returnCode the return code
184     *
185     * @return the link for the return code
186     *
187     * @throws CmsRpcException if something goes wrong
188     */
189    CmsReturnLinkInfo getLinkForReturnCode(String returnCode) throws CmsRpcException;
190
191    /**
192     * Gets the resource state for a resource with a given path.<p>
193     *
194     * @param structureId the resource structure id
195     *
196     * @return the resource state of the resource
197     *
198     * @throws CmsRpcException if something goes wrong
199     */
200    CmsResourceState getResourceState(CmsUUID structureId) throws CmsRpcException;
201
202    /**
203     * Returns a unique filename for the given base name and the parent folder.<p>
204     *
205     * @param parentFolder the parent folder of the file
206     * @param baseName the proposed file name
207     *
208     * @return the unique file name
209     *
210     * @throws CmsRpcException if something goes wrong
211     */
212    String getUniqueFileName(String parentFolder, String baseName) throws CmsRpcException;
213
214    /**
215     * Returns the user info.<p>
216     *
217     * @return the user info
218     *
219     * @throws CmsRpcException in case something goes wrong
220     */
221    UserInfo getUserInfo() throws CmsRpcException;
222
223    /**
224     * Returns a link for the OpenCms workplace that will reload the whole workplace, switch to the explorer view, the
225     * site of the given explorerRootPath and show the folder given in the explorerRootPath.<p>
226     *
227     * @param structureId the structure id of the resource for which to open the workplace
228     *
229     * @return a link for the OpenCms workplace that will reload the whole workplace, switch to the explorer view, the
230     *         site of the given explorerRootPath and show the folder given in the explorerRootPath.
231     *
232     * @throws CmsRpcException if something goes wrong
233     */
234    String getWorkplaceLink(CmsUUID structureId) throws CmsRpcException;
235
236    /**
237     * Gets the workplace link for the given path.
238     *
239     * @param path the path
240     * @return the workplace link for the path
241     * @throws CmsRpcException if something goes wrong
242     */
243    String getWorkplaceLinkForPath(String path) throws CmsRpcException;
244
245    /**
246     * Loads the user settings for the current user.<p>
247     *
248     * @return the user settings for the current user
249     *
250     * @throws CmsRpcException if something goes wrong
251     */
252    CmsUserSettingsBean loadUserSettings() throws CmsRpcException;
253
254    /**
255     * Locks the given resource with a temporary lock if it exists.<p>
256     * If the resource does not exist yet, the closest existing ancestor folder will check if it is lockable.<p>
257     *
258     * @param sitePath the site path of the resource to lock
259     *
260     * @return <code>null</code> if successful, an error message if not
261     *
262     * @throws CmsRpcException if something goes wrong
263     */
264    String lockIfExists(String sitePath) throws CmsRpcException;
265
266    /**
267     * Locks the given resource with a temporary lock if it exists.<p>
268     * If the resource does not exist yet, the closest existing ancestor folder will check if it is lockable.<p>
269     *
270     * @param sitePath the site path of the resource to lock
271     * @param loadTime the time when the requested resource was loaded
272     *
273     * @return <code>null</code> if successful, an error message if not
274     *
275     * @throws CmsRpcException if something goes wrong
276     */
277    String lockIfExists(String sitePath, long loadTime) throws CmsRpcException;
278
279    /**
280     * Locks the given resource with a temporary lock.<p>
281     *
282     * @param structureId the structure id of the resource to lock
283     *
284     * @return <code>null</code> if successful, an error message if not
285     *
286     * @throws CmsRpcException if something goes wrong
287     */
288    String lockTemp(CmsUUID structureId) throws CmsRpcException;
289
290    /**
291     * Locks the given resource with a temporary lock.<p>
292     * Locking will fail in case the requested resource has been changed since the given load time.<p>
293     *
294     * @param structureId the resource structure id
295     * @param loadTime the time when the requested resource was loaded
296     *
297     * @return <code>null</code> if successful, an error message if not
298     *
299     * @throws CmsRpcException if something goes wrong
300     */
301    String lockTemp(CmsUUID structureId, long loadTime) throws CmsRpcException;
302
303    /**
304     * Generates core data for prefetching in the host page.<p>
305     *
306     * @return the core data
307     *
308     * @throws CmsRpcException if something goes wrong
309     */
310    CmsCoreData prefetch() throws CmsRpcException;
311
312    /**
313     * Saves the user settings for the current user.<p>
314     *
315     * @param userSettings the new values for the user settings
316     * @param edited the keys of the user settings which were actually edited
317     *
318     * @throws CmsRpcException if something goes wrong
319     */
320    void saveUserSettings(Map<String, String> userSettings, Set<String> edited) throws CmsRpcException;
321
322    /**
323     * Sets the categories of the given resource. Will remove all other categories.<p>
324     *
325     * @param structureId the resource structure id
326     * @param categories the categories to set
327     *
328     * @throws CmsRpcException if something goes wrong
329     */
330    void setResourceCategories(CmsUUID structureId, List<String> categories) throws CmsRpcException;
331
332    /**
333     * Sets the show editor help flag.<p>
334     *
335     * @param showHelp the show help flag
336     *
337     * @throws CmsRpcException if something goes wrong
338     */
339    void setShowEditorHelp(boolean showHelp) throws CmsRpcException;
340
341    /**
342     * Writes the tool-bar visibility into the session cache.<p>
343     *
344     * @param visible <code>true</code> if the tool-bar is visible
345     *
346     * @throws CmsRpcException if something goes wrong
347     */
348    void setToolbarVisible(boolean visible) throws CmsRpcException;
349
350    /**
351     * Unlocks the given resource.<p>
352     *
353     * @param structureId the structure id of the resource to unlock
354     *
355     * @return <code>null</code> if successful, an error message if not
356     *
357     * @throws CmsRpcException if something goes wrong
358     */
359    String unlock(CmsUUID structureId) throws CmsRpcException;
360
361    /**
362     * Unlocks the given resource.<p>
363     *
364     * @param rootPath the root path of the resource to unlock
365     *
366     * @return <code>null</code> if successful, an error message if not
367     *
368     * @throws CmsRpcException if something goes wrong
369     */
370    String unlock(String rootPath) throws CmsRpcException;
371
372    /**
373     * Performs a batch of validations and returns the results.<p>
374     *
375     * @param validationQueries a map from field names to validation queries
376     *
377     * @return a map from field names to validation results
378     *
379     * @throws CmsRpcException if something goes wrong
380     */
381    Map<String, CmsValidationResult> validate(Map<String, CmsValidationQuery> validationQueries) throws CmsRpcException;
382
383    /**
384     * Performs a batch of validations using a custom form validator class.<p>
385     *
386     * @param formValidatorClass the class name of the form validator
387     * @param validationQueries a map from field names to validation queries
388     * @param values the map of all field values
389     * @param config the form validator configuration string
390     *
391     * @return a map from field names to validation results
392     *
393     * @throws CmsRpcException if the RPC call goes wrong
394     */
395    Map<String, CmsValidationResult> validate(
396        String formValidatorClass,
397        Map<String, CmsValidationQuery> validationQueries,
398        Map<String, String> values,
399        String config)
400    throws CmsRpcException;
401
402}