Discussions Application API

Last modified by Manuel Leduc on 2021/03/17 21:55

cogAPI of the Discussions Application.
TypeOther
CategoryAPI
Developed by

Manuel Leduc

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1

Description

The Discussions API allows to interact with the Discussions Application data model.
It can be used to query existing discussion, but also to integrates new kinds of discussions and new kinds of discussions into XWiki.

Discussion Context Service

The discussions context service provides the operations to get and create discussions contexts as well as link discussions and discussion contexts together.

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import java.util.List;
import java.util.Optional;

import org.xwiki.component.annotation.Role;
import org.xwiki.contrib.discussions.domain.Discussion;
import org.xwiki.contrib.discussions.domain.DiscussionContext;
import org.xwiki.stability.Unstable;

/**
 * This service provides the operation to manipulate discussion context objects.
 *
 * @version $Id$
 * @since 1.0
 */

@Role
@Unstable
public interface DiscussionContextService
{
   /**
     * Creates a discussion context.
     *
     * @param name the discussion context name
     * @param description the discussion context description
     * @param referenceType the type of the entity referenced by the discussion context
     * @param entityReference the reference of the entity referenced by the discussion context
     * @return the initialized discussion context
     */

    Optional<DiscussionContext> create(String name, String description, String referenceType, String entityReference);

   /**
     * If a discussion context already exist with the given reference type and entity reference, it is returned. If it
     * does not the discussion context is created with the name and description passed in parameter, and it then
     * returned.
     *
     * @param name the name
     * @param description the description
     * @param referenceType the reference type
     * @param entityReference the entity reference
     * @return the found or created discussion context
     */

    Optional<DiscussionContext> getOrCreate(String name, String description, String referenceType,
        String entityReference);

   /**
     * Link a discussion context and a discussion.
     *
     * @param discussionContext the discussion context
     * @param discussion the discussion
     */

   void link(DiscussionContext discussionContext, Discussion discussion);

   /**
     * Unlink a discussion context and a discussion.
     *
     * @param discussionContext the discussion context
     * @param discussion the discussion
     */

   void unlink(DiscussionContext discussionContext, Discussion discussion);

   /**
     * Search and retrieve a discussion context by its reference.
     *
     * @param reference the discussion context reference
     * @return the discussion context
     */

    Optional<DiscussionContext> get(String reference);

   /**
     * Returns the list of discussion contexts linked to the discussion reference.
     *
     * @param reference the discussion reference
     * @return the list of discussion contexts
     */

    List<DiscussionContext> findByDiscussionReference(String reference);

   /**
     * @return {@code true} if the current actor can create a discussion context, {@code false} otherwise
     */

   boolean canCreateDiscussionContext();

   /**
     * @param reference the reference of the discussion content
     * @return {@code true} if the current user can view the discussion context, {@code false} otherwise
     */

   boolean canViewDiscussionContext(String reference);
}

Discussion Service

The discussions service provides the operations to get and create discussions and as well a select discussions according to the discussions contexts to which they are linked.

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import java.util.List;
import java.util.Optional;

import org.xwiki.component.annotation.Role;
import org.xwiki.contrib.discussions.domain.Discussion;
import org.xwiki.stability.Unstable;

/**
 * This service provides the operation to manipulate discussion objects.
 *
 * @version $Id$
 * @since 1.0
 */

@Unstable
@Role
public interface DiscussionService
{
   /**
     * Creates a discussion with a main document.
     *
     * @param title the discussion title
     * @param description the discussion description
     * @param mainDocument the main document to view the discussion
     * @return the created discussion
     */

    Optional<Discussion> create(String title, String description, String mainDocument);

   /**
     * Search for a discussion linked to the provided list of discussion contexts. If it exists, it is directly
     * returned. If it does not, it is initialized with the provided title and description, and linked to the list of
     * discussion contexts.
     *
     * @param title the title
     * @param description the description
     * @param discussionContexts the list of discussion contexts
     * @return the created or found discussion
     */

    Optional<Discussion> getOrCreate(String title, String description, List<String> discussionContexts);

   /**
     * Search and retrieve a discussion by its reference.
     *
     * @param reference the discussion reference
     * @return the discussion
     */

    Optional<Discussion> get(String reference);

   /**
     * @param reference a discussion reference
     * @return {@code true} if the current user has the right to view the discussion, {@code false} otherwise
     */

   boolean canRead(String reference);

   /**
     * @param reference a discussion reference
     * @return {@code true} if the current user has the rights to write in the discussion, {@code false} otherwise
     */

   boolean canWrite(String reference);

   /**
     * Find a list of discussions that are linked at least to the list of discussion context passed in parameter.
     *
     * @param discussionContextReferences a list of discussion context references
     * @return the list discussions attached to the list of discussion contexts
     */

    List<Discussion> findByDiscussionContexts(List<String> discussionContextReferences);

   /**
     * Count the number of discussions linked to a context with the given entity references values.
     *
     * @param type the type of the entity reference
     * @param references the reference values of the entity references
     * @return the count result
     */

   long countByEntityReferences(String type, List<String> references);

   /**
     * Find the list of discussions linked to discussion contexts with the given entity references.
     *
     * @param type the entity reference type
     * @param references the entity reference values
     * @param offset the offset
     * @param limit the limit
     * @return tge paginated list of discussions
     */

    List<Discussion> findByEntityReferences(String type, List<String> references, Integer offset, Integer limit);

   /**
     * Set the update date of the discussion to now.
     *
     * @param discussionReference the reference of the discussion to update
     */

   void touch(String discussionReference);

   /**
     * Return true if a discussion exists with the request discussion context entity.
     *
     * @param type the type of the discussion context entity
     * @param reference the reference of the discussion context entity
     * @return {@code true} if a discussion context is found, {@code false} otherwise
     */

   boolean findByDiscussionContext(String type, String reference);

   /**
     * @return {@code true} if the current user can create a discussion, {@code false} otherwise
     */

   boolean canCreateDiscussion();

   /**
     * @param reference the reference of the discussion
     * @return {@code true} if the current user is allowed to view the discussion, {@code false} otherwise
     */

   boolean canViewDiscussion(String reference);
}

Message Service

The message services provides the operations to get, create and count messages.

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import java.util.List;
import java.util.Optional;

import org.xwiki.component.annotation.Role;
import org.xwiki.contrib.discussions.domain.Discussion;
import org.xwiki.contrib.discussions.domain.Message;
import org.xwiki.model.reference.EntityReference;
import org.xwiki.rendering.syntax.Syntax;
import org.xwiki.stability.Unstable;

/**
 * This service provides the operation to manipulate message objects.
 *
 * @version $Id$
 * @since 1.0
 */

@Role
@Unstable
public interface MessageService
{
   /**
     * Creates a message for the current user.
     *
     * @param content the message content
     * @param syntax the syntax of the content of the message
     * @param discussionReference the discussion reference
     * @return the created message
     */

    Optional<Message> create(String content, Syntax syntax, String discussionReference);

   /**
     * Creates a message for a specific user.
     *
     * @param content the message content
     * @param syntax the syntax of the content of the message
     * @param discussionReference the discussion reference
     * @param authorType the author type
     * @param authorReference the author reference
     * @return the create message
     */

    Optional<Message> create(String content, Syntax syntax, String discussionReference,
        String authorType, String authorReference);

   /**
     * Creates a message for a specific user.
     *
     * @param content the message content
     * @param syntax the syntax of the content of the message
     * @param discussionReference the discussion reference
     * @param authorType the author type
     * @param authorReference the author reference
     * @param notify {@code true} if the notifications for the message creation can be sent, {@code false}
     *     otherwise
     * @return the create message
     */

    Optional<Message> create(String content, Syntax syntax, String discussionReference, String authorType,
        String authorReference,
       boolean notify);

   /**
     * Get a message by its unique reference.
     *
     * @param reference the reference
     * @return the message
     */

    Optional<Message> getByReference(String reference);

   /**
     * Returns the paginated list of messages of the discussion.
     *
     * @param discussionReference the discussion reference
     * @param offset the offset
     * @param limit the limit
     * @return the list of messages
     */

    List<Message> getByDiscussion(String discussionReference, int offset, int limit);

   /**
     * Returns the count of messages of a discussion.
     *
     * @param discussion the discussion
     * @return the count of messages
     */

   long countByDiscussion(Discussion discussion);

   /**
     * Checks if the message can be deleted by the current user.
     *
     * @param message the message
     * @return {@code true} of the current user can delete the message. {@code false} otherwise
     */

   boolean canDelete(Message message);

   /**
     * Delete a message.
     *
     * @param reference the message reference
     * @param discussionReference the reference of the discussion of the message
     */

   void delete(String reference, String discussionReference);

   /**
     * Safely renders the content of a message.
     *
     * @param messageReference the reference of the message to render
     * @return the result of the rendering in html
     */

    String renderContent(String messageReference);

   /**
     * Load a message object by its entity reference.
     *
     * @param entityReference the entity reference of the message object
     * @return the message object
     */

    Optional<Message> getByEntity(EntityReference entityReference);
}

Discussions Rights Service

The discussions rights services provides the right operations for the discussions entities.

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import org.xwiki.component.annotation.Role;
import org.xwiki.contrib.discussions.domain.Discussion;
import org.xwiki.contrib.discussions.domain.Message;
import org.xwiki.model.reference.DocumentReference;
import org.xwiki.model.reference.EntityReference;
import org.xwiki.stability.Unstable;

/**
 * Service to manage the rights of the discussions entities.
 *
 * @version $Id$
 * @since 1.0
 */

@Role
@Unstable
public interface DiscussionsRightService
{
   /**
     * @return {@code true} if the current user can create a discussion, {@code false} otherwise
     */

   boolean canCreateDiscussion();

   /**
     * @return {@code true} if the current user can create a discussion context, {@code false} otherwise
     */

   boolean canCreateDiscussionContext();

   /**
     * @param discussion the discussion page
     * @return {@code true} of the current user can read the discussion, {@code false otherwise}
     */

   boolean canReadDiscussion(EntityReference discussion);

   /**
     * @param discussion the discussion page
     * @return {@code true} if the current user can write in the discussion, {@code false} otherwise.
     */

   boolean canWriteDiscussion(DocumentReference discussion);

   /**
     * @param discussionContext the discussion context page
     * @return {@code true} if the current user can write in the discussion context, {@code false} otherwise.
     */

   boolean canWriteDiscussionContext(DocumentReference discussionContext);

   /**
     * @param message the message
     * @param discussion the discussion page
     * @return {@code true} if the current user can delete the message, {@code false} otherwise
     */

   boolean canDeleteMessage(Message message, DocumentReference discussion);

   /**
     * @param discussion the discussion
     * @return {@code} true if the current user is an administrator of the discussion, {@code} false otherwise
     */

   boolean isAdminDiscussion(DocumentReference discussion);

   /**
     * Allow the user to read the discussion.
     *
     * @param discussion the discussion
     * @param user the user
     */

   void setRead(Discussion discussion, DocumentReference user);

   /**
     * Allow the user to write the discussion.
     *
     * @param discussion the discussion
     * @param user the user
     */

   void setWrite(Discussion discussion, DocumentReference user);
}

Discussion Actor Service

The discussions actor service provides the resolve operation to resolve a discussion actor according to its reference.
The type of the actor is used as an hint to find the discussion actor component to use to resolve an actor reference.

For instance, for an actor of type user and identifier xwiki:XWiki.U1, the UserDiscussionsActorsService will be used.

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import java.util.Optional;
import java.util.stream.Stream;

import org.xwiki.component.annotation.Role;
import org.xwiki.contrib.discussions.domain.ActorDescriptor;
import org.xwiki.stability.Unstable;

/**
 * Returns an actor descriptor from an actor reference.
 *
 * @version $Id$
 * @since 1.0
 */

@Unstable
@Role
public interface DiscussionsActorService
{
   /**
     * Returns an actor descriptor from an actor reference.
     *
     * @param reference the actor reference
     * @return the actor description, or {@link Optional#empty()} in case of error during the resolution
     */

    Optional<ActorDescriptor> resolve(String reference);

   /**
     * Returns the list of actors involved in a discussion. The definition of this involvement is up to interpretation
     * and can be implemented freely by services that implement this role.
     *
     * @param discussionReference the discussion reference
     * @return the list of actors involved in a discuission
     */

    Stream<ActorDescriptor> listUsers(String discussionReference);

   /**
     * Returns the number of users involved in a discussion.
     *
     * @param discussionReference the discussion reference
     * @return the number of users involved in the request discussion
     */

   long countUsers(String discussionReference);
}

Discussions Actor Service Resolver

The discussion actor service resolve provides the operations to get the discussion actor service for the requested type.

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import java.util.Optional;

import org.xwiki.component.annotation.Role;
import org.xwiki.stability.Unstable;

/**
 * Resolve a {@link DiscussionsActorService} according to the requested actor type.
 *
 * @version $Id$
 * @since 1.0
 */

@Role
@Unstable
public interface DiscussionsActorServiceResolver
{
   /**
     * Returns an actor service for the requested type.
     *
     * @param type the type
     * @return the actor service, {@link Optional#empty()} if the resolution failed
     */

    Optional<DiscussionsActorService> get(String type);
}

Discussions Script Service

The discussions script service provides the operations to interact with the discussions data model from XWiki Scripting.

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import java.util.List;
import java.util.Map;

import javax.inject.Inject;
import javax.inject.Named;
import javax.inject.Singleton;

import org.slf4j.Logger;
import org.xwiki.component.annotation.Component;
import org.xwiki.contrib.discussions.domain.ActorDescriptor;
import org.xwiki.contrib.discussions.domain.Discussion;
import org.xwiki.contrib.discussions.domain.DiscussionContext;
import org.xwiki.contrib.discussions.domain.Message;
import org.xwiki.contrib.discussions.internal.QueryStringService;
import org.xwiki.rendering.parser.ParseException;
import org.xwiki.rendering.syntax.Syntax;
import org.xwiki.script.service.ScriptService;
import org.xwiki.script.service.ScriptServiceManager;
import org.xwiki.stability.Unstable;

import static java.util.Collections.singletonList;
import static org.apache.commons.lang3.exception.ExceptionUtils.getRootCauseMessage;

/**
 * Discussions script service.
 *
 * @version $Id$
 * @since 1.0
 */

@Unstable
@Named(DiscussionsScriptService.ROLEHINT)
@Component
@Singleton
public class DiscussionsScriptService implements ScriptService
{
   /**
     * The role hint of this component.
     */

   public static final String ROLEHINT = "discussions";

   @Inject
   private DiscussionContextService discussionContextService;

   @Inject
   private DiscussionService discussionService;

   @Inject
   private MessageService messageService;

   @Inject
   private QueryStringService queryStringService;

   @Inject
   private DiscussionsActorServiceResolver actorsServiceResolver;

   @Inject
   private ScriptServiceManager scriptServiceManager;

   @Inject
   private Logger logger;

   /**
     * Creates a discussion context.
     *
     * @param name the name
     * @param description the description
     * @param referenceType the entity reference type
     * @param entityReference the entity reference
     * @return the created discussion context
     */

   public DiscussionContext createDiscussionContext(String name, String description, String referenceType,
        String entityReference)
   {
       if (this.discussionContextService.canCreateDiscussionContext()) {
           return this.discussionContextService.create(name, description, referenceType, entityReference).orElse(null);
       } else {
           return null;
       }
   }

   /**
     * Get a discussion context. Creates it if it does not already exist.
     *
     * @param name the discussion context name
     * @param description the discussion context description
     * @param referenceType the entity reference type
     * @param entityReference the entity reference
     * @return the request discussion context
     */

   public DiscussionContext getOrCreateDiscussionContext(String name, String description, String referenceType,
        String entityReference)
   {
       if (this.discussionContextService.canCreateDiscussionContext()) {
           return this.discussionContextService.getOrCreate(name, description, referenceType, entityReference)
               .orElse(null);
       } else {
           return null;
       }
   }

   /**
     * Creates a discussion with an URL to the main discussion view page.
     *
     * @param title the discussion title
     * @param description the discussion description
     * @param mainDocument the main document to view the discussion
     * @return the created discussion
     */

   public Discussion createDiscussion(String title, String description, String mainDocument)
   {
       return this.discussionService.create(title, description, mainDocument).orElse(null);
   }

   /**
     * Retrieve a discussion by its reference.
     *
     * @param reference the discussion reference
     * @return the discussion, {@code null} if not found
     */

   public Discussion getDiscussion(String reference)
   {
       if (this.discussionService.canViewDiscussion(reference)) {
           return this.discussionService.get(reference).orElse(null);
       } else {
           return null;
       }
   }

   /**
     * Retrieve a discussion context by its reference.
     *
     * @param reference the discussion context reference
     * @return the discussion context, {@code null} if not found
     */

   public DiscussionContext getDiscussionContext(String reference)
   {
       if (this.discussionContextService.canViewDiscussionContext(reference)) {
           return this.discussionContextService.get(reference).orElse(null);
       } else {
           return null;
       }
   }

   /**
     * Create a message in a discussion for the current user.
     *
     * @param content the content
     * @param syntax the syntax of the content of the message
     * @param discussion the discussion
     * @return the created message
     */

   public Message createMessage(String content, String syntax, Discussion discussion)
   {
       if (this.discussionService.canWrite(discussion.getReference())) {
           try {
               return this.messageService.create(content, Syntax.valueOf(syntax), discussion.getReference())
                   .orElse(null);
           } catch (ParseException e) {
               this.logger.warn("Malformed syntax [{}]. Cause: [{}].", syntax, getRootCauseMessage(e));
               return null;
           }
       } else {
           return null;
       }
   }

   /**
     * Return a paginated list of messages of a discussion.
     *
     * @param discussion the discussion
     * @param offset the offset
     * @param limit the limit
     * @return the messages of the discussion
     */

   public List<Message> getMessagesByDiscussion(Discussion discussion, int offset, int limit)
   {
       if (this.discussionService.canViewDiscussion(discussion.getReference())) {
           return this.messageService.getByDiscussion(discussion.getReference(), offset * limit, limit);
       } else {
           return null;
       }
   }

   /**
     * Return the number of messages in a discussion.
     *
     * @param discussion the discussion
     * @return the messages count of the discussion
     */

   public long countMessagesByDiscussion(Discussion discussion)
   {
       if (this.discussionService.canViewDiscussion(discussion.getReference())) {
           return this.messageService.countByDiscussion(discussion);
       } else {
           return 0;
       }
   }

   /**
     * Update a param with newParameterMap values and returns a string representation.
     *
     * @param parameterMap the query string
     * @param newParameterMap the new parameters to overload or add
     * @return the string representation
     */

   public String updateQueryString(Map<String, Object> parameterMap, Map<String, Object> newParameterMap)
   {
       return this.queryStringService.getString(parameterMap, newParameterMap);
   }

   /**
     * Find the discussions linked to exactly the provided list of discussion context reference.
     *
     * @param discussionContextReferences the list of discussion context reference
     * @return the list of discussions
     */

   public List<Discussion> findByDiscussionContexts(List<String> discussionContextReferences)
   {
       return this.discussionService.findByDiscussionContexts(discussionContextReferences);
   }

   /**
     * Links a discussion and a discussion context.
     *
     * @param discussion the discussion
     * @param discussionContext the discussion context
     */

   public void linkDiscussionToDiscussionContext(Discussion discussion, DiscussionContext discussionContext)
   {
       this.discussionContextService.link(discussionContext, discussion);
   }

   /**
     * Unlinks a discussion and a discussion context.
     *
     * @param discussion the discussion
     * @param discussionContext the discussion context
     */

   public void unlinkDiscussionToDiscussionContext(Discussion discussion, DiscussionContext discussionContext)
   {
       this.discussionContextService.unlink(discussionContext, discussion);
   }

   /**
     * Returns an actor descriptor for the provided reference according to its type.
     *
     * @param type the type of the actor
     * @param reference the reference of the actor
     * @return the {@link ActorDescriptor}, or {@code null} in case of error during the resolution
     */

   public ActorDescriptor getActorDescriptor(String type, String reference)
   {
       return this.actorsServiceResolver.get(type)
           .flatMap(resolver -> resolver.resolve(reference))
           .orElse(null);
   }

   /**
     * @param <S> the type of the {@link ScriptService}
     * @param serviceName the name of the sub {@link ScriptService}
     * @return the {@link ScriptService} or null of none could be found
     */

   @SuppressWarnings("unchecked")
   public <S extends ScriptService> S get(String serviceName)
   {
       return (S) this.scriptServiceManager.get(ROLEHINT + '.' + serviceName);
   }

   /**
     * Safely renders the content of the message.
     *
     * @param messageReference the message reference
     * @return the content of the message rendered in html
     */

   public String renderMessageContent(String messageReference)
   {
       return this.messageService.renderContent(messageReference);
   }

   /**
     * Checks if the provided discussion reference is linked to the request entity type and entity reference.
     *
     * @param discussionReference a discussion reference
     * @param entityType an entity type
     * @param entityReference an entity reference
     * @return {@code true} if the discussion is linked to an discussion context with the required entity type and
     *     entity reference
     */

   public boolean hasDiscussionContext(String discussionReference, String entityType, String entityReference)
   {
       return this.discussionService.findByEntityReferences(entityType, singletonList(entityReference), null, null)
           .stream()
           .anyMatch(it -> it.getReference().equals(discussionReference));
   }

   /**
     * Returns the first discussion found which is link to a discussion context with the provided entity type and entity
     * reference.
     *
     * @param entityType the discussion context entity type
     * @param entityReference the discussion context entity reference
     * @return a discussion linked to the request discussion context
     * @since 1.1
     */

   @Unstable
   public Discussion getDiscussionByDiscussionContext(String entityType, String entityReference)
   {
        List<Discussion> discussions =
           this.discussionService.findByEntityReferences(entityType, singletonList(entityReference), 0, 1);
        Discussion discussion;
       if (discussions.isEmpty()) {
            discussion = null;
       } else {
            discussion = discussions.get(0);
       }

       return discussion;
   }
}

Discussions Rights Script Service

/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This 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; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software 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 software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */

package org.xwiki.contrib.discussions;

import javax.inject.Inject;
import javax.inject.Named;
import javax.inject.Singleton;

import org.xwiki.component.annotation.Component;
import org.xwiki.contrib.discussions.domain.Discussion;
import org.xwiki.contrib.discussions.domain.Message;
import org.xwiki.model.reference.DocumentReference;
import org.xwiki.script.service.ScriptService;
import org.xwiki.security.authorization.ContextualAuthorizationManager;
import org.xwiki.security.authorization.Right;
import org.xwiki.stability.Unstable;

/**
 * Script service dedicated to the discussions rights.
 *
 * @version $Id$
 * @since 1.0
 */

@Unstable
@Component
@Named("discussions.rights")
@Singleton
public class DiscussionRightsScriptService implements ScriptService
{
   @Inject
   private DiscussionService discussionService;

   @Inject
   private MessageService messageService;

   @Inject
   private DiscussionsRightService discussionsRightService;

   @Inject
   private ContextualAuthorizationManager authorizationManager;

   /**
     * @param discussionReference the discussion reference
     * @return {@code true} if the current user can read the discussion, {@code false} otherwise
     */

   public boolean canReadDiscussion(String discussionReference)
   {
       return this.discussionService.canRead(discussionReference);
   }

   /**
     * @param discussionReference the discussion reference
     * @return {@code true} if the current user can write in the discussion, {@code false} otherwise
     */

   public boolean canWriteDiscussion(String discussionReference)
   {
       return this.discussionService.canWrite(discussionReference);
   }

   /**
     * @param message the message
     * @return {@code true} if the current user can remove the message, {@code false} otherwise
     */

   public boolean canDeleteMessage(Message message)
   {
       return this.messageService.canDelete(message);
   }

   /**
     * Allows a user to read a discussion. This operation requires the programming right.
     *
     * @param discussion a discussion
     * @param user a user
     */

   public void setRead(Discussion discussion, DocumentReference user)
   {
       if (this.authorizationManager.hasAccess(Right.PROGRAM)) {
           this.discussionsRightService.setRead(discussion, user);
       }
   }

   /**
     * Allows a user to write on a discussion. This operation requires the programming right.
     *
     * @param discussion a discussion
     * @param user a user
     */

   public void setWrite(Discussion discussion, DocumentReference user)
   {
       if (this.authorizationManager.hasAccess(Right.PROGRAM)) {
           this.discussionsRightService.setWrite(discussion, user);
       }
   }
}

Scripting Examples

{{velocity}}
## Create a discussion context and a discussion and links the together.
#set ($discussionContext = $services.discussions.createDiscussionContext('', '', 'example', 'contextA'))
#set ($discussion = $services.discussions.createDiscussion('New discusssion', 'This is a new example discussion.'))
#set ($discard = $services.discussions.linkDiscussionToDiscussionContext($discussion, $discussionContext))
## Add a message to the discussion.
#set ($message = $services.discussions.createMessage('**Message** content', 'xwiki/2.1', $discussion)
## Get the discussions linked to some discussion contexts
$services.discussions.findByDiscussionContexts([$discussionContext.reference, 'reference2'])
## Checks if the current user can view the discussion
$services.discussions.rights.canReadDiscussion($discussion.reference)
{{/velocity}}
Tags:
    

Get Connected