com.communote.server.core.external

Interface ExternalObjectManagement

All Known Implementing Classes:

ExternalObjectManagementBase, ExternalObjectManagementImpl

public interface ExternalObjectManagement

Management functions for the external objects

Author:

Communote GmbH - http://www.communote.com/

Method Summary

Modifier and Type	Method and Description
ExternalObject	assignExternalObject(Long blogId, ExternalObject externalObject) Assign an external object to a topic.
void	assignOrUpdateExternalObjects(Long blogId, Collection<ExternalObject> externalObjects) Assign or update a collection of external objects.
<T> T	getExternalObject(Long topicId, Long externalObjectId, Converter<Pair<Blog,ExternalObject>,T> converter) Get an external object which is identified by the given ID and is assigned to the given topic.
Collection<ExternalObject>	getExternalObjects(Long blogId) Return the external objects that are assigned to the given blog.
boolean	hasExternalObjects(Long blogId) Return whether a given blog has external objects.
boolean	isExternalObjectAssigned(Long blogId, String externalSystemId, String externalObjectId) Check if a external object is assigned to a blog
void	registerExternalObjectSource(ExternalObjectSource source) Register an external object source.
void	removeExternalObject(Long externalObjectId) Remove the external object with the given ID.
void	removeExternalObject(Long blogId, String externalSystemId, String externalObjectId) Remove an external object from a blog.
void	removeExternalObjectTrusted(Long externalObjectId) Remove the external object from the blog it is assigned to.
void	replaceExternalObjects(Long blogId, Collection<ExternalObject> externalObjects) Replace the external objects assigned to a blog with the provided ones.
void	unregisterExternalObjectSource(ExternalObjectSource source) Remove an external object source that was registered with registerExternalObjectSource(ExternalObjectSource).
ExternalObject	updateExternalObject(Long blogId, ExternalObject externalObject) Update an existing external object.

Method Detail

assignExternalObject

ExternalObject assignExternalObject(Long blogId,
                                    ExternalObject externalObject)
                             throws BlogNotFoundException,
                                    BlogAccessException,
                                    ExternalObjectAlreadyAssignedException,
                                    TooManyExternalObjectsPerTopicException,
                                    ExternalSystemNotConfiguredException

Assign an external object to a topic. If the external object is already assigned to the topic nothing will happen. If it is assigned to another topic an exception will be thrown. If it is not assigned it is created, the provided properties are added and it is assigned to the topic.

Parameters:

blogId - the ID of the blog to assign the external object to

externalObject - object describing the external object to assign

Returns:

the assigned external object

Throws:

BlogNotFoundException - in case the blog was not found

BlogAccessException - in case the user is not a manager of the blog

ExternalObjectAlreadyAssignedException - in case the external object is assigned to another blog than the provided one

ExternalSystemNotConfiguredException - in case the externalSystemId of the external object does not belong to a registered or active external object source. A source is considered active if it provides a valid configuration.

TooManyExternalObjectsPerTopicException - in case there are already assignments for the external source and topic and the configuration does not allow more assignments

assignOrUpdateExternalObjects

void assignOrUpdateExternalObjects(Long blogId,
                                   Collection<ExternalObject> externalObjects)
                            throws BlogNotFoundException,
                                   BlogAccessException,
                                   ExternalObjectAlreadyAssignedException,
                                   TooManyExternalObjectsPerTopicException,
                                   ExternalSystemNotConfiguredException

Assign or update a collection of external objects. If one of the provided external objects is already assigned to the blog it will be updated. If it is not assigned it will be added. The update works as updateExternalObject(Long, ExternalObject) and the assign like assignExternalObject(Long, ExternalObject)

Parameters:

blogId - the ID of the blog to assign the external objects to

externalObjects - objects describing the external objects to assign or update. To find an existing external object the external ID and the external system ID members are used if set otherwise the ID member is used.

Throws:

BlogNotFoundException - in case the blog was not found

BlogAccessException - in case the user is not a manager of the blog

ExternalObjectAlreadyAssignedException - in case one of the external objects is assigned to another blog than the provided one

ExternalSystemNotConfiguredException - in case the externalSystemId of the external object does not belong to a registered or active external object source. A source is considered active if it provides a valid configuration.

TooManyExternalObjectsPerTopicException - in case the configuration does not allow that many assignments

getExternalObject

<T> T getExternalObject(Long topicId,
                        Long externalObjectId,
                        Converter<Pair<Blog,ExternalObject>,T> converter)
                 throws BlogNotFoundException,
                        BlogAccessException

Get an external object which is identified by the given ID and is assigned to the given topic.

Parameters:

topicId - the ID of the topic

externalObjectId - the internal ID of the external object

converter - the converter to transform the external object in the result object

Returns:

the converted result or null if the external object does not exist

Throws:

BlogNotFoundException - in case the topic does not exist

BlogAccessException - in case the current user has no access to the given topic

getExternalObjects

Collection<ExternalObject> getExternalObjects(Long blogId)
                                       throws BlogNotFoundException,
                                              BlogAccessException

Return the external objects that are assigned to the given blog. The properties will not be loaded. Use the property management to get them.

Parameters:

blogId - the ID of the blog

Returns:

the external objects of the topic. The collection will be empty if the blog has no external objects.

Throws:

BlogNotFoundException - in case the blog does not exist

BlogAccessException - in case the current user has no read access to the blog

hasExternalObjects

boolean hasExternalObjects(Long blogId)
                    throws BlogNotFoundException,
                           BlogAccessException

Return whether a given blog has external objects.

Parameters:

blogId - the ID of the blog

Returns:

true if there is at least one external object, false otherwise

Throws:

BlogNotFoundException - in case the blog does not exist

BlogAccessException - in case the current user has no read access to the blog

isExternalObjectAssigned

boolean isExternalObjectAssigned(Long blogId,
                                 String externalSystemId,
                                 String externalObjectId)
                          throws BlogAccessException,
                                 BlogNotFoundException

Check if a external object is assigned to a blog

Parameters:

blogId - the ID of the blog the external object is checked for beeing assigned to

externalSystemId - the ID of the external system

externalObjectId - the ID that identifies the external object within the external system

Returns:

true if the object is assigned, false otherwise

Throws:

BlogAccessException - in case the current user has no read access to the blog

BlogNotFoundException - in case there is no blog for the given ID

registerExternalObjectSource

void registerExternalObjectSource(ExternalObjectSource source)
                           throws ExternalObjectSourceAlreadyExistsException

Register an external object source. After registering a source external objects with the ID of the source can be linked to topics.

Parameters:

source - the source to register

Throws:

ExternalObjectSourceAlreadyExistsException - in case there is already a source with the same ID

removeExternalObject

void removeExternalObject(Long externalObjectId)
                   throws BlogAccessException,
                          NotFoundException

Remove the external object with the given ID. If the removed external object is the last of the external system, the blog access rights added for that external system will be removed too.

Parameters:

externalObjectId - the ID of the external object to remove

Throws:

BlogAccessException - in case the current user is not manager of the blog

NotFoundException - in case the external object does not exist

removeExternalObject

void removeExternalObject(Long blogId,
                          String externalSystemId,
                          String externalObjectId)
                   throws BlogNotFoundException,
                          BlogAccessException

Remove an external object from a blog. If the removed external object is the last of the external system, the blog access rights added for that external system will be removed too.

Parameters:

blogId - ID of the blog

externalSystemId - identifier of the external system

externalObjectId - identifier of the external object in the external system

Throws:

BlogNotFoundException - in case the blog does not exist

BlogAccessException - in case the current user is not manager of the blog

removeExternalObjectTrusted

void removeExternalObjectTrusted(Long externalObjectId)
                          throws NotFoundException,
                                 AuthorizationException

Remove the external object from the blog it is assigned to. If the removed external object is the last of the external system, the blog access rights added for that external system will be removed too.

Similar to the 'trusted' methods of BlogRightsManagement this method requires that the current user is client manager.

Parameters:

externalObjectId - ID of the external object

Throws:

NotFoundException - in case the external object does not exist

AuthorizationException - in case the current user is not client manager

replaceExternalObjects

void replaceExternalObjects(Long blogId,
                            Collection<ExternalObject> externalObjects)
                     throws BlogNotFoundException,
                            BlogAccessException,
                            ExternalObjectAlreadyAssignedException,
                            TooManyExternalObjectsPerTopicException,
                            ExternalSystemNotConfiguredException

Replace the external objects assigned to a blog with the provided ones. This method works like assignOrUpdateExternalObjects(Long, Collection) but additionally removes any assigned external object that is not in the provided external objects.

Parameters:

blogId - the ID of the blog whose external objects should be replaced

externalObjects - the new external objects to replace the existing with

Throws:

BlogNotFoundException - in case the blog does not exist

BlogAccessException - in case the current user is not manager of the blog

ExternalObjectAlreadyAssignedException - in case one of the external objects is assigned to another blog than the provided one

ExternalSystemNotConfiguredException

TooManyExternalObjectsPerTopicException

unregisterExternalObjectSource

void unregisterExternalObjectSource(ExternalObjectSource source)

Remove an external object source that was registered with registerExternalObjectSource(ExternalObjectSource). If the source was not registered the call is ignored

Parameters:

source - the source to remove

updateExternalObject

ExternalObject updateExternalObject(Long blogId,
                                    ExternalObject externalObject)
                             throws BlogNotFoundException,
                                    BlogAccessException,
                                    NotFoundException,
                                    ExternalObjectAlreadyAssignedException

Update an existing external object. This covers modification of the name and the properties. The properties handling is as follows: If a property key and group combination does not exist, the property is created. If the property key and group combination exists, the value is updated. In case the value is null, the property is removed.

Parameters:

blogId - the ID of the blog the external object is assigned to

externalObject - object with details about the external object which are used to resolve the assigned object and update its data. To find the existing external object the external ID and the external system ID members are used if set otherwise the ID member is used.

Returns:

the updated external object

Throws:

BlogNotFoundException - in case the blog does not exist

BlogAccessException - in case the current user is not manager of the blog

NotFoundException - in case the external object does not exist

ExternalObjectAlreadyAssignedException - in case the external object is already assigned to another blog than the provided one