org.bonitasoft.engine.api.ApplicationAPI Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of bonita-common Show documentation
Show all versions of bonita-common Show documentation
Bonita Common is the useful layer common to bonita-client and bonita-server
/**
* Copyright (C) 2019 Bonitasoft S.A.
* Bonitasoft, 32 rue Gustave Eiffel - 38000 Grenoble
* This library is free software; you can redistribute it and/or modify it under the terms
* of the GNU Lesser General Public License as published by the Free Software Foundation
* version 2.1 of the License.
* This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
* See the GNU Lesser General Public License for more details.
* You should have received a copy of the GNU Lesser General Public License along with this
* program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
* Floor, Boston, MA 02110-1301, USA.
**/
package org.bonitasoft.engine.api;
import java.util.List;
import org.bonitasoft.engine.business.application.Application;
import org.bonitasoft.engine.business.application.ApplicationCreator;
import org.bonitasoft.engine.business.application.ApplicationImportPolicy;
import org.bonitasoft.engine.business.application.ApplicationMenu;
import org.bonitasoft.engine.business.application.ApplicationMenuCreator;
import org.bonitasoft.engine.business.application.ApplicationMenuNotFoundException;
import org.bonitasoft.engine.business.application.ApplicationMenuUpdater;
import org.bonitasoft.engine.business.application.ApplicationNotFoundException;
import org.bonitasoft.engine.business.application.ApplicationPage;
import org.bonitasoft.engine.business.application.ApplicationPageNotFoundException;
import org.bonitasoft.engine.business.application.ApplicationUpdater;
import org.bonitasoft.engine.exception.AlreadyExistsException;
import org.bonitasoft.engine.exception.CreationException;
import org.bonitasoft.engine.exception.DeletionException;
import org.bonitasoft.engine.exception.ExportException;
import org.bonitasoft.engine.exception.ImportException;
import org.bonitasoft.engine.exception.SearchException;
import org.bonitasoft.engine.exception.UpdateException;
import org.bonitasoft.engine.search.SearchOptions;
import org.bonitasoft.engine.search.SearchResult;
/**
* This API allows to list and manage Bonita Living Applications ({@link Application}).
*
* @author Elias Ricken de Medeiros
* @see org.bonitasoft.engine.business.application.Application
* @since 6.4
*/
public interface ApplicationAPI {
/**
* Creates a new {@link Application} based on the supplied {@link ApplicationCreator}
*
* @param applicationCreator creator describing characteristics of application to be created
* @return the created Application
* @throws AlreadyExistsException if an application already exists with the same name
* @throws CreationException if an error occurs during the creation
* @see Application
* @see ApplicationCreator
*/
Application createApplication(ApplicationCreator applicationCreator)
throws AlreadyExistsException, CreationException;
/**
* Retrieves an {@link Application} from its identifier.
*
* @param applicationId the application identifier
* @return an Application from its identifier.
* @throws ApplicationNotFoundException if no application is found for the given identifier
* @see Application
*/
Application getApplication(final long applicationId) throws ApplicationNotFoundException;
/**
* Deletes an {@link Application} by its identifier. All related
* {@link org.bonitasoft.engine.business.application.ApplicationPage}s and
* {@link org.bonitasoft.engine.business.application.ApplicationMenu}s will be automatically deleted.
*
* @param applicationId the Application identifier
* @throws DeletionException if an error occurs during the deletion
* @see Application
* @see org.bonitasoft.engine.business.application.ApplicationPage
* @see org.bonitasoft.engine.business.application.ApplicationMenu
*/
void deleteApplication(long applicationId) throws DeletionException;
/**
* Updates an {@link Application} based on the information supplied by the {@link ApplicationUpdater}
*
* @param applicationId a long representing the application identifier
* @param updater an ApplicationUpdater describing the fields to be updated.
* @return the Application as it is after the update.
* @throws ApplicationNotFoundException if no Application is found for the given id
* @throws AlreadyExistsException if another Application already exists with the new name value
* @throws UpdateException if an error occurs during the update
* @see Application
* @see ApplicationUpdater
*/
Application updateApplication(long applicationId, ApplicationUpdater updater)
throws ApplicationNotFoundException, UpdateException, AlreadyExistsException;
/**
* Searches for {@link Application}s with specific search criteria. Use
* {@link org.bonitasoft.engine.business.application.ApplicationSearchDescriptor} to
* know the available filters.
*
* @param searchOptions the search criteria. See {@link SearchOptions} for details.
* @return a {@link SearchResult} containing the number and the list of applications matching the search criteria.
* @throws SearchException if an error occurs during search
* @see Application
* @see org.bonitasoft.engine.business.application.ApplicationSearchDescriptor
* @see SearchOptions
* @see SearchResult
*/
SearchResult searchApplications(final SearchOptions searchOptions) throws SearchException;
/**
* Creates an {@link ApplicationPage}
*
* @param applicationId the identifier of the {@link org.bonitasoft.engine.business.application.Application} to
* which the
* {@link org.bonitasoft.engine.page.Page} will be associated
* @param pageId the identifier of Page to be associated to the Application
* @param token the token that this Page will take in this ApplicationPage. The token must
* be unique for a given application and
* should contain only alpha numeric characters and the following special characters '-', '.', '_' or '~'. In
* addition, the following words are reserved
* key words and cannot be used
* as token: 'api', 'content', 'theme'.
* @return the created {@link ApplicationPage}
* @throws AlreadyExistsException if the token is already used by another ApplicationPage on this
* Application
* @throws CreationException if an error occurs during the creation
* @throws ApplicationNotFoundException if the referenced application does not exist.
* @see ApplicationPage
* @see Application
* @see org.bonitasoft.engine.page.Page
*/
ApplicationPage createApplicationPage(long applicationId, long pageId, String token)
throws AlreadyExistsException, CreationException,
ApplicationNotFoundException;
/**
* Retrieves the {@link ApplicationPage} for the given {@code Application} token and {@code ApplicationPage} token
*
* @param applicationToken the Application name
* @param applicationPageToken the ApplicationPage token
* @return the {@link ApplicationPage} for the given {@code Application} token and {@code ApplicationPage} token
* @throws ApplicationPageNotFoundException if no {@link ApplicationPage} is found for the given
* Application token and
* ApplicationPage token
* @see ApplicationPage
*/
ApplicationPage getApplicationPage(String applicationToken, String applicationPageToken)
throws ApplicationPageNotFoundException;
/**
* Retrieves the {@link ApplicationPage} from its identifier
*
* @param applicationPageId the {@code ApplicationPage} identifier
* @return the {@link ApplicationPage} from its identifier
* @throws ApplicationPageNotFoundException if no {@link ApplicationPage} is found for the given identifier
* @see ApplicationPage
*/
ApplicationPage getApplicationPage(long applicationPageId) throws ApplicationPageNotFoundException;
/**
* Deletes an {@link ApplicationPage} by its identifier. All related
* {@link org.bonitasoft.engine.business.application.ApplicationMenu} will be
* automatically deleted.
*
* @param applicationPageId the {@code ApplicationPage} identifier
* @throws DeletionException if an error occurs during the deletion
* @see ApplicationPage
* @see org.bonitasoft.engine.business.application.ApplicationMenu
*/
void deleteApplicationPage(long applicationPageId) throws DeletionException;
/**
* Searches for {@link ApplicationPage}s with specific search criteria.
*
* @param searchOptions the search criteria. See {@link SearchOptions} for details. Use
* {@link org.bonitasoft.engine.business.application.ApplicationPageSearchDescriptor} to know the available
* filters.
* @return a {@link SearchResult} containing the number and the list of
* {@code org.bonitasoft.engine.business.application.ApplicationPageSearchDescriptor}s
* matching the search criteria.
* @throws SearchException if an error occurs during the search execution
* @see ApplicationPage
* @see org.bonitasoft.engine.business.application.ApplicationPageSearchDescriptor
* @see SearchOptions
* @see SearchResult
*/
SearchResult searchApplicationPages(final SearchOptions searchOptions) throws SearchException;
/**
* Defines which {@link ApplicationPage} will represent the {@link Application} home page
*
* @param applicationId the {@code Application} identifier
* @param applicationPageId the identifier of the {@code ApplicationPage} to be used as home page
* @throws UpdateException if an error occurs during the update
* @throws ApplicationNotFoundException if no {@code Application} is found with the given id
* @see Application
* @see ApplicationPage
*/
void setApplicationHomePage(long applicationId, long applicationPageId)
throws UpdateException, ApplicationNotFoundException;
/**
* Retrieves the {@link ApplicationPage} defined as the {@link Application} home page
*
* @param applicationId the {@code Application} identifier
* @return the t{@code ApplicationPage} defined as {@code Application} home page
* @throws ApplicationPageNotFoundException if no home page is found for the given application
* @see Application
* @see ApplicationPage
*/
ApplicationPage getApplicationHomePage(long applicationId) throws ApplicationPageNotFoundException;
/**
* Creates a {@link ApplicationMenu} based on the supplied {@link ApplicationMenuCreator}. The new created
* {@code ApplicationMenu} will be ordered at the
* last position of its level with an auto generated index.
*
* @param applicationMenuCreator creator describing the characteristics of the {@code ApplicationMenu} to be created
* @return the created {@code ApplicationMenu}
* @throws CreationException if an error occurs during the creation
* @see ApplicationMenu
* @see ApplicationMenuCreator
*/
ApplicationMenu createApplicationMenu(ApplicationMenuCreator applicationMenuCreator) throws CreationException;
/**
* Updates an {@link org.bonitasoft.engine.business.application.ApplicationMenu} based on the information supplied
* by the
* {@link org.bonitasoft.engine.business.application.ApplicationMenuUpdater}.
*
* When the {@code ApplicationMenu} index is updated all other {@code ApplicationMenu}s in the same level will have
* indexes automatically updated in order
* to keep indexes coherency. For instance, when an {@code ApplicationMenu} is moved from index 4 to index 2, the
* {@code ApplicationMenu} previously at
* index 2 will be moved to index 3 and the {@code ApplicationMenu} previously at index 3 will be moved to index 4.
*
*
* @param applicationMenuId the {@code ApplicationMenu} identifier
* @param updater the {@code ApplicationMenuUpdater} describing the fields to be updated.
* @return the {@code ApplicationMenu} up to date
* @throws ApplicationMenuNotFoundException if no {@code ApplicationMenu} is found for the given identifier
* @throws UpdateException if an exception occurs during the update
* @see org.bonitasoft.engine.business.application.ApplicationMenu
* @see org.bonitasoft.engine.business.application.ApplicationMenuUpdater
*/
ApplicationMenu updateApplicationMenu(long applicationMenuId, ApplicationMenuUpdater updater)
throws ApplicationMenuNotFoundException, UpdateException;
/**
* Retrieves the {@link ApplicationMenu} from its identifier
*
* @param applicationMenuId the {@code ApplicationMenu} menu identifier
* @return the {@code ApplicationMenu} from its identifier
* @throws ApplicationMenuNotFoundException if no {@code ApplicationMenu} is found for the given identifier
* @see ApplicationMenu
*/
ApplicationMenu getApplicationMenu(long applicationMenuId) throws ApplicationMenuNotFoundException;
/**
* Deletes an {@link ApplicationMenu} by its identifier. All children {@code ApplicationMenu} will be automatically
* deleted.
*
* When an {@code ApplicationMenu} is deleted all others {@code ApplicationMenu}s having index greater than the
* index of deleted {@code ApplicationMenu} in
* the same level will be automatically updated in order to keep indexes coherency.
*
*
* @param applicationMenuId the {@code ApplicationMenu} identifier
* @throws DeletionException if an error occurs during the deletion
* @see ApplicationMenu
*/
void deleteApplicationMenu(long applicationMenuId) throws DeletionException;
/**
* Searches for {@link ApplicationMenu}s with specific search criteria.
*
* @param searchOptions the search criteria. See {@link SearchOptions} for details. Use
* {@link org.bonitasoft.engine.business.application.ApplicationMenuSearchDescriptor} to know the available
* filters
* @return a {@link SearchResult} containing the number and the list of {@code ApplicationMenu}s matching the search
* criteria.
* @throws SearchException if an error occurs during search
* @see ApplicationMenu
* @see SearchOptions
* @see org.bonitasoft.engine.business.application.ApplicationMenuSearchDescriptor
* @see SearchResult
*/
SearchResult searchApplicationMenus(final SearchOptions searchOptions) throws SearchException;
/**
* Return all pages names that can be accessed by the profile through applications.
* The portal use this method to calculate all permissions for a user.
*
* @param profileId
* the id of the profile
* @return
* list of page name accessible by the profile through applications
*/
List getAllPagesForProfile(long profileId);
/**
* Returns all pages names that can be accessed by the profile through applications.
* The portal use this method to calculate all permissions for a user.
*
* WARNING: this method is Experimental, it might change in later versions
*
* @param profile
* the name of the profile
* @return
* list of page name accessible by the profile through applications
* @since 7.8
*/
@Experimental
List getAllPagesForProfile(String profile);
/**
* Exports the {@link org.bonitasoft.engine.business.application.Application}s which identifier is in
* {@code applicationIds}
*
* @param applicationIds the identifiers of {@code Application}s to be exported
* @return a byte array representing the content of XML file containing the exported {@code Application}s
* @throws ExportException if an exception occurs during the export.
* @see org.bonitasoft.engine.business.application.Application
*/
byte[] exportApplications(long... applicationIds) throws ExportException;
/**
* Imports {@link org.bonitasoft.engine.business.application.Application}s based on a XML file content.
*
* Before importing {@code Application}s ensure that all {@link org.bonitasoft.engine.profile.Profile}s referenced
* by {@code Application}s and all
* {@link org.bonitasoft.engine.page.Page}s referenced by
* {@link org.bonitasoft.engine.business.application.ApplicationPage}s are available.
*
* - When the {@code Profile} does not exist the {@code Application} will be imported, but no {@code Profile} will
* be associated to it. An
* {@link org.bonitasoft.engine.api.ImportError} will be added to the {@link org.bonitasoft.engine.api.ImportStatus}
* related to this {@code Application}.
*
* - When a {@code Page} does not exist the related {@code ApplicationPage} and
* {@link org.bonitasoft.engine.business.application.ApplicationMenu}s
* pointing to this {@code ApplicationPage} will not be created. An {@code ImportError} will be added to the
* {@code ImportStatus} related to the
* {@code Application} containing this {@code ApplicationPage}.
*
*
*
* @param xmlContent a byte array representing the content of XML file containing the applications to be imported.
* @param policy the {@link org.bonitasoft.engine.business.application.ApplicationImportPolicy} used to execute the
* import
* @return a {@link java.util.List} of {@link org.bonitasoft.engine.api.ImportStatus} representing the
* {@code ImportStatus} for each imported
* {@code Application}
* @throws ImportException if an error occurs during the import
* @throws org.bonitasoft.engine.exception.AlreadyExistsException if one of applications being imported already
* exists and the policy
* {@code ApplicationImportPolicy.FAIL_ON_DUPLICATES} is used
* @see org.bonitasoft.engine.business.application.Application
* @see org.bonitasoft.engine.business.application.ApplicationImportPolicy
* @see org.bonitasoft.engine.api.ImportStatus
* @see org.bonitasoft.engine.api.ImportError
* @see org.bonitasoft.engine.business.application.ApplicationPage
* @see org.bonitasoft.engine.business.application.ApplicationMenu
* @see org.bonitasoft.engine.profile.Profile
* @see org.bonitasoft.engine.page.Page
*/
List importApplications(final byte[] xmlContent, final ApplicationImportPolicy policy)
throws ImportException, AlreadyExistsException;
}