Package nl.gx.webmanager.services.contentapi

Interface MediaRepositoryManagementService

  • public interface MediaRepositoryManagementService
    This class offers APIs for operations with media items.

    • Method Detail

      • createDownloadMediaItem

        MediaItem createDownloadMediaItem​(Website website)
        Creates a new download media item and returns it.
        Parameters:
        website - Website for which to create the download media item
        Returns:
        The download media item that was created, or null if an error occurred

      • createImageMediaItem

        MediaItem createImageMediaItem​(Website website)
        Creates a new image media item and returns it.
        Parameters:
        website - Website for which to create the image media item
        Returns:
        The image media item that was created, or null if an error occurred

      • createPageMediaItem

        MediaItem createPageMediaItem​(Website website,
                              Page page)
        Creates a new page media item and a page media item version for each existing page version of the provided page.
        Parameters:
        website - Website for which to create the page media item
        page - Page for which to create the page media item versions
        Returns:
        The page media item that was created, or null if an error occurred

      • createMediaItemPageVersion

        MediaItemPageVersion createMediaItemPageVersion​(PageVersion pageVersion)
        Creates a new media item page version associated with the specified page version and returns it. If a media item page version is already associated with the page version, that version is returned instead.
        Parameters:
        pageVersion - The page version for which the media item page version should be created
        Returns:
        • either the created media item page version, if the specified page version did not yet have an associated media item page version.
        • If a media item page version is already associated with the page version, that version is returned instead.
        • or null if createing the media item page version failed

      • createPageModelMediaItem

        @Deprecated
MediaItem createPageModelMediaItem​(Website website,
                                   nl.gx.webmanager.cms.pagemodel.PageModel pageModel)
        Deprecated.
        Page models are removed from XC.
        Creates a new media item based on a page model.
        Parameters:
        website - Website for which to create the media item.
        pageModel - The page model to base the media item on.
        Returns:
        The newly created media item, or null if an error occurred

      • createMediaItem

        MediaItem createMediaItem​(Website website,
                          String type)
        Creates a new media item of the specified type in the current editing language and returns it.
        Parameters:
        website - Website for which to create the media item
        type - String identifying the type of media item (see nl.gx.webmanager.cms.mediarepository.MediaItem for static definitions of all available types) NB: Cannot be used for media items of type page or page model.
        Returns:
        The media item that was created, or null if an error occurred

      • createMediaItem

        MediaItem createMediaItem​(Website website,
                          String type,
                          Language language)
        Creates a new media item of the specified type in a given language and returns it.
        Parameters:
        website - Website for which to create the media item
        type - String identifying the type of media item (see nl.gx.webmanager.cms.mediarepository.MediaItem for static definitions of all available types) NB: Cannot be used for media items of type page or page model.
        language - the language of the media item, null for the current editing language
        Returns:
        The media item that was created, or null if an error occurred

      • createMediaItemFromPageVersion

        MediaItem createMediaItemFromPageVersion​(PageVersion pageVersion,
                                         String type)
                                  throws NoAuthorizationException
        Creates a new media item as a copy of a given page version. The type of the new media item must be an element holder type, otherwise an IllegalArgumentException is thrown. The following information is copied from the page version to the media item:
        • Title
        • Language
        • Content area, i.e. elements and links
        • Lead text and image
        • Publication and expiration date
        • URL title
        • Html title
        • Meta description and keywords
        • Include in search engine flag
        • SEO priority and update frequency
        • Remark
        The media item will be created in the initial, unpublished workflow state.
        Parameters:
        pageVersion - The page version to copy.
        type - String identifying the type of media item (see nl.gx.webmanager.cms.mediarepository.MediaItem for static definitions of all available types)
        Returns:
        The created media item.
        Throws:
        NoAuthorizationException - If the user has no rights to create the media item version.
        IllegalArgumentException - When the parameters are empty or invalid.
        Since:
        10.32.0

      • createMediaTerm

        MediaTerm createMediaTerm​(Website website,
                          String termName)
        Creates a new media term with the specified term name. If a term with the given name already exists then that MediaTerm is returned.
        Parameters:
        website - The website for which to create the media term.
        termName - The name of the term to create.
        Returns:
        The created media term.

      • createClassification

        MediaTermClassification createClassification​(String classification)
        Creates a new term classification and returns it. If the classification is null or empty, the method will log a warning and return null. If the classification already exists, that classification is returned and no new classification will be created. If the classification does not yet exist, it will be created and returned. In case of an exception, null will be returned.
        Parameters:
        classification - The name of the classification to create
        Returns:
        The created classification or the classification that already existed with this name

      • copyMediaItem

        MediaItem copyMediaItem​(MediaItem mediaItem)
                 throws NoAuthorizationException
        Copies the given media item. The copied media item will belong to the same web site as the source media item.

        Regarding authorization an user needs to have CREATE permission on the media repository. If and only if the media item contains elements each element requires CREATE permission for the user, and the user needs UPDATE permission on the media repository.

        Steps performed:

        • Permissions of the current user are checked
        • A Event.Type.PRE media item event of type MediaItemEvent.COPY is fired
        • Requested media item is copied
        • If the media item contains elements all elements are copied
        • If for an element the authorization checks as described above fails the copy is cancelled
        • A Event>Type.POST media item event of type MediaItemEvent.CREATE is fired
        • A Event.Type.POST media item event of type MediaItemEvent.COPY is fired

        Note: currently only supports article, page model and media items of a custom content type, and NOT page, multimedia, image and download.

        Parameters:
        mediaItem - Media item to copy.
        Returns:
        The copied media item.
        Throws:
        NoAuthorizationException - If user has no rights to copy the media item.

      • createMediaItemVersion

        MediaItemVersion createMediaItemVersion​(MediaItemVersion original,
                                        Language language)
                                 throws NoAuthorizationException
        Copy a media item version to a given (possibly other) language.
        Parameters:
        original - the original MediaItemVersion to base the new version on
        language - the language of the new version, null for the language of the original version
        Returns:
        the new version
        Throws:
        NoAuthorizationException - if there is no authorization

      • createMediaItemVersionFromPageVersion

        MediaItemVersion createMediaItemVersionFromPageVersion​(MediaItem mediaItem,
                                                       PageVersion pageVersion)
                                                throws NoAuthorizationException
        Creates a new media item version as a copy of a given page version and adds it to the given media item. The following information is copied from the page version to the media item version:
        • Title
        • Language
        • Content area, i.e. elements and links
        • Lead text and image
        • Publication and expiration date
        • URL title
        • Html title
        • Meta description and keywords
        • Include in search engine flag
        • SEO priority and update frequency
        • Remark
        The media item version will be created in the initial, unpublished workflow state.
        Parameters:
        mediaItem - The media item to which to add the new version.
        pageVersion - The page version to copy.
        Returns:
        The created media item version.
        Throws:
        NoAuthorizationException - If the user has no rights to create the media item version.
        IllegalArgumentException - When the parameters are empty or invalid.
        Since:
        10.32.0

      • copyMediaItem

        MediaItem copyMediaItem​(Website website,
                        MediaItem mediaItem)
                 throws NoAuthorizationException
        Copies the given media item to the target website. If no website is specified than the copied media item is created for the same website as the source media item.

        For a detailed description see copyMediaItem(MediaItem).

        Parameters:
        website - Website which will be the owner of the copy.
        mediaItem - Media item to copy.
        Returns:
        The copied media item.
        Throws:
        NoAuthorizationException - If user has no rights to copy the media item.

      • copyMediaItemVersion

        MediaItem copyMediaItemVersion​(MediaItemVersion mediaItemVersion)
                        throws NoAuthorizationException
        Copies the given media item version to a new media item. The website where the copied mediaitem is created is the same as the website of the given mediaitem version.
        Parameters:
        mediaItemVersion - The version to make a copy of
        Returns:
        The new created media item as copy
        Throws:
        NoAuthorizationException - If user has no rights to copy the media item.

      • copyMediaItem

        MediaItem copyMediaItem​(Website website,
                        MediaItem mediaItem,
                        boolean retainTerms)
                 throws NoAuthorizationException
        Copies the given media item to the target website. If no website is specified than the copied media item is created for the same website as the source media item.

        For a detailed description see copyMediaItem(MediaItem).

        Parameters:
        website - Website which will be the owner of the copy.
        mediaItem - Media item to copy.
        retainTerms - If true, copying a mediaItem to a website which has no access to the mediaItem's website media repository the assigned terms are cloned, if false they are not retained.
        Returns:
        The copied media item.
        Throws:
        NoAuthorizationException - If user has no rights to copy the media item.

      • deleteMediaItem

        boolean deleteMediaItem​(MediaItem mediaItem)
        Deletes the given media item.
        Parameters:
        mediaItem - Media item to delete
        Returns:
        true if deleting the media item succeeded, false otherwise

      • deleteMediaItemVersion

        boolean deleteMediaItemVersion​(MediaItemVersion mediaItemVersion)
        Deletes the given media item version.
        Parameters:
        mediaItemVersion - Media item version to delete
        Returns:
        true if deleting the media item version succeeded, false otherwise

      • deleteMediaTerm

        void deleteMediaTerm​(MediaTerm mediaTerm)
        Deletes a media term.
        Parameters:
        mediaTerm - Media term to delete.

      • getAllMediaItems

        MediaItem[] getAllMediaItems​(String mediaType)
        NB: THIS METHOD UNCONDITIONALLY RETRIEVES ALL MEDIAITEMS OF A PARTICULAR TYPE. ONLY USE IT IN CASE IT IS FOR SURE THAT USING IT WILL NOT CAUSE PERFORMANCE ISSUES. This method retrieves all media items of a particular type.
        Parameters:
        mediaType - Media type to retrieve the media items from
        Returns:
        Array of all media items of the specified type

      • getMediaItemsIterator

        CloseableIterator<MediaItemVersion> getMediaItemsIterator​(String mediaType)
        This method retrieves all media items of a particular type. Instead of the getAllMediaItems method, it returns an iterator for far less memory consuming functionality.
        Parameters:
        mediaType - Media type to retrieve the media items from
        Returns:
        Iterator over all media items of the specified type
        Since:
        10.30.0

      • reorderElements

        boolean reorderElements​(MediaItemArticleVersion mediaItemArticleVersion,
                        Element[] elements)
        Reorders all the elements of a media item article version. The given elements defines the new ordering of elements. Note that there is no authorization required to reorder elements.
        Parameters:
        mediaItemArticleVersion - The media item article version which elements should be reordered.
        elements - Elements that defines the new ordering of the media item article version's elements.
        Returns:
        Returns true if reorder succeeded, false otherwise.

      • getMediaItemFilterInstance

        MediaItemFilter getMediaItemFilterInstance()
        Creates and returns an instance of a MediaItemFilter with default values.

        The default values of the created instance are :

        • result range : 0 - 1000
        • status : all public workflowmodel states
        • publicationDateTo : the current date and time
        Returns:
        new MediaItemFilter instance

      • getMediaItemSortOptionsInstance

        MediaItemSortOptions getMediaItemSortOptionsInstance()
        Creates an instance of MediaItemSortOptions.
        Returns:
        new MediaItemSortOptions

      • getMediaItems

        MediaSearchResult getMediaItems​(Website website,
                                MediaItemFilter filter,
                                MediaItemSortOptions sortOptions)
        Performs the search of media items based on filter search criteria.
        Parameters:
        website - Source web site from which the media repository is accessed.
        filter - the search criteria
        sortOptions - the sort options
        Returns:
        the search result containing selected media items

      • performWorkflowAction

        @Deprecated
void performWorkflowAction​(MediaItemVersion mediaItemVersion,
                           WorkflowAction workflowAction)
                    throws UnExecutableWorkflowActionException
        Deprecated.
        Not for public use. This method is expected to be retained only as a package private method. Replaced by WorkflowService#performWorkflowAction
        Performs the given workflowAction to progress this mediaItemVersion to the next state.
        Parameters:
        mediaItemVersion - the mediaItemVersion
        workflowAction - the workflowAction
        Throws:
        UnExecutableWorkflowActionException - If the given workflow action is invalid.

      • performPostUpdateActions

        @Deprecated
void performPostUpdateActions​(MediaItemVersion mediaItemVersion)
        Deprecated.
        Not for public use. Replaced by the generic event mechanism that triggers the update.
        Tells WebManager a media item version has been updated. Must be used after setting some properties of the media item version to ensure that dependent components do their job.

        Currently the SEO service (Search Engine Optimization) is instructed to update the media item version's friendly URL if necessary.

        Parameters:
        mediaItemVersion - The media item version that has been updated.

      • addBroaderNarrowerTermRelation

        void addBroaderNarrowerTermRelation​(MediaTerm broaderTerm,
                                    MediaTerm narrowerTerm)
        Adds a "broader" / "narrower" hierarchical term relation. If you add this relation and then invoke the getNarrowerTerms() method on the term passed by the broaderTerm argument, it will return an array containing the term passed by the narrowerTerm argument and vice versa.
        Parameters:
        broaderTerm - The term that will be the "broader" part in the relation.
        narrowerTerm - The term that will be the "narrower" part in the relation.

      • addRelatedToTermRelation

        void addRelatedToTermRelation​(MediaTerm term1,
                              MediaTerm term2)
        Adds a "related to" relational term relation. This relation is commutative, meaning that when "term1 relates to term2" then also "term2 relates to term1".
        Parameters:
        term1 - The first term.
        term2 - The second term.

      • addUsedByUsedForTermRelation

        void addUsedByUsedForTermRelation​(MediaTerm usedByTerm,
                                  MediaTerm usedForTerm)
        Adds a "used by" / "used for" relational term relation. If you add this relation and then invoke the getUsedForTerms() method on the term passed by the usedByTerm argument, it will return an array containing the term passed by the usedForTerm argument and vice versa.
        Parameters:
        usedByTerm - The term that will be the "used by" part in the relation.
        usedForTerm - The term that will be the "used for" part in the relation.

      • removeTermRelations

        void removeTermRelations​(MediaTerm term1,
                         MediaTerm term2)
        Removes any relations that exist between two terms. This method is commutative, meaning that it doesn't matter in which order the terms are supplied to this method.
        Parameters:
        term1 - One of the terms that might have an existing relation.
        term2 - The other of the terms that might have an existing relation.

      • updateDiscussion

        void updateDiscussion​(MediaItemVersion mediaItemVersion,
                      DiscussionConfiguration oldDiscussionConfiguration)
        Updates the discussion for a media item version.
        Parameters:
        mediaItemVersion - the media item version
        oldDiscussionConfiguration - the old discussion configuration