/*
* JBoss, a division of Red Hat
* Copyright 2011, Red Hat Middleware, LLC, and individual
* contributors as indicated by the @authors tag. See the
* copyright.txt in the distribution for a full listing of
* individual contributors.
*
* 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.gatein.registration;
import org.gatein.pc.api.PortletContext;
import org.gatein.wsrp.registration.PropertyDescription;
import javax.xml.namespace.QName;
import java.util.Map;
/**
* An interface allowing users of the Registration service to customize different aspects of how Consumers are handled.
* Methods of this interface are used by RegistrationManager to make appropriate decisions. Implementations of this
* interface <strong>MUST</strong> provide a no-argument constructor for instantiation from the class name.
* <p/>
* <strong>IMPORTANT</strong>: RegistrationPolicy instances are wrapped using a {@link
* org.gatein.registration.policies.RegistrationPolicyWrapper}. As a result, using <code>instanceof</code> on a
* RegistrationPolicy will probably result in unexpected result. To retrieve the actual class of the RegistrationPolicy
* instance in use, use {@link #getRealClass()} (or {@link #getClassName()} to retrieve the class name). If, for some
* reason, the actual RegistrationPolicy instance is needed, use {@link org.gatein.registration.policies.RegistrationPolicyWrapper#unwrap(RegistrationPolicy)},
* though it is not recommended to manipulate actual RegistrationPolicy instances directly.
*
* @author <a href="mailto:chris.laprun@jboss.com">Chris Laprun</a>
* @version $Revision: 11406 $
* @since 2.6
*/
public interface RegistrationPolicy
{
/**
* Examines and determines whether the given registration properties are adequate for the Consumer associated with
* the given identity. This method is called before a Registration is created and thus allows users to decide whether
* or not to reject a given registration if not satisfied with the given registration properties.
*
* @param registrationProperties a Map containing the registration properties in the form of property name (QName) -
* property value (Object) mappings
* @param consumerIdentity the Consumer identity (as returned by {@link #getConsumerIdFrom(String,
* java.util.Map)}) for which the registration properties must be ascertained
* @param expectations a Map containing the registration expectations of the producer
* @param manager the RegistrationManager in which context this RegistrationPolicy is invoked
* @throws IllegalArgumentException if any of the registration properties is invalid for the specified Consumer
* @throws RegistrationException if an exception occured in the registration service
*/
void validateRegistrationDataFor(Map<QName, Object> registrationProperties, String consumerIdentity,
final Map<QName, ? extends PropertyDescription> expectations, final RegistrationManager manager)
throws IllegalArgumentException, RegistrationException;
/**
* Generates a registration handle based on the database identity of the Registration. This allows users to customize
* the registration handle format if they want to prevent exposure of database-related data.
*
* @param registrationId the database identity of the Registration for which a handle is required.
* @return a registration handle for the Registration associated with the specified identifier.
* @throws IllegalArgumentException if the specified registration identity if <code>null</code> or empty
*/
String createRegistrationHandleFor(String registrationId) throws IllegalArgumentException;
/**
* Determines the ConsumerGroup name to which the Consumer associated with the specified name should be assigned with
* or <code>null</code> if the Consumer should not be automatically assigned to a ConsumerGroup. This method is
* called during the Consumer creation process to see if the Consumer should be automatically added to a
* ConsumerGroup.
*
* @param consumerName the name of the Consumer being created
* @return the name of the ConsumerGroup the Consumer must be automatically added to or <code>null</code> if the
* Consumer will not be automatically added to a ConsumerGroup at creation
* @throws IllegalArgumentException if the specified Consumer name if <code>null</code> or empty
*/
String getAutomaticGroupNameFor(String consumerName) throws IllegalArgumentException;
/**
* Obtains a consumer identity which uniquely identifies a Consumer in function of the consumer name and registration
* properties. This is potentially necessary because Consumer names are not guaranteed to be unique (even though the
* specification states that they should).
*
* @param consumerName the consumer name
* @param registrationProperties a Map containing the registration properties in the form of property name (QName) -
* property value (Object) mappings. Producer implementations might use the
* registration properties to provide secure Consumer identity.
* @return the consumer identity
* @throws InvalidConsumerDataException if the Policy examines the specified registration properties to determine the
* Consumer identity and decides that they are not in a proper state
* @throws IllegalArgumentException if the specified Consumer name if <code>null</code> or empty
*/
String getConsumerIdFrom(String consumerName, Map<QName, Object> registrationProperties)
throws IllegalArgumentException, InvalidConsumerDataException;
/**
* Determines if the specified Consumer name is acceptable. This method is called before a Consumer is created and
* before a unique Consumer identity is created. This is in particular used if the Policy mandates that Consumer
* names must be unique.
*
* @param consumerName the name of the Consumer as passed during the registration process
* @param manager the RegistrationManager in which context this RegistrationPolicy is invoked
* @throws IllegalArgumentException if the specified Consumer name if <code>null</code> or empty
* @throws RegistrationException if an exception occurred in the Registration service
*/
void validateConsumerName(String consumerName, final RegistrationManager manager)
throws IllegalArgumentException, RegistrationException;
/**
* Determines if the specified ConsumerGroup name is acceptable. This method is called before a ConsumerGroup is
* created.
*
* @param groupName the name of the ConsumerGroup to be created
* @param manager the RegistrationManager in which context this RegistrationPolicy is invoked
* @throws IllegalArgumentException if the specified ConsumerGroup name if <code>null</code> or empty
* @throws RegistrationException if an exception occurred in the Registration service
*/
void validateConsumerGroupName(String groupName, RegistrationManager manager) throws IllegalArgumentException, RegistrationException;
/**
* Whether this RegistrationPolicy allows access to the specified named operation on the portlet identified by the specified PortletContext in the context of the specified
* Registration.
*
* @param portletContext the PortletContext identifying which portlet we're trying to interact with
* @param registration the registration in which context the operation will take place
* @param operation the name of the operation, which should be the calling method's name (without parameters). Currently, only {@link org.gatein.pc.api.PortletInvoker}'s
* methods and getServiceDescription are checked
* @return <code>true</code> if the operation is allowed in the given context, <code>false</code> otherwise
*/
boolean allowAccessTo(PortletContext portletContext, Registration registration, String operation);
/**
* Whether or not this RegistrationPolicy is wrapped in a RegistrationPolicyWrapper. Mostly targeted at the internal implementation.
*
* @return <code>true</code> whether this RegistrationPolicy is wrapped in in a {@link org.gatein.registration.policies.RegistrationPolicyWrapper}, <code>false</code> otherwise
*/
boolean isWrapped();
/**
* Retrieves this RegistrationPolicy's class name. Note that this retrieves the underlying class name if the RegistrationPolicy is wrapped so this method is guaranteed to
* always
* return the "real" implementation class name, not {@link org.gatein.registration.policies.RegistrationPolicyWrapper}'s class name. :)
*
* @return this RegistrationPolicy's "real" class name, i.e. this class' name if it's not wrapped or the wrapped RegistrationPolicy's class name if it is
*/
String getClassName();
/**
* Retrieves this RegistrationPolicy's real class object. Guaranteed to retrieve this class instance if this RegistrationPolicy is not wrapped, or the wrapped
* RegistrationPolicy's class if it is.
*
* @return this class instance if this RegistrationPolicy is not wrapped, or the wrapped RegistrationPolicy's class if it is.
*/
Class<? extends RegistrationPolicy> getRealClass();
}