001: /******************************************************************************
002: * JBoss, a division of Red Hat *
003: * Copyright 2006, Red Hat Middleware, LLC, and individual *
004: * contributors as indicated by the @authors tag. See the *
005: * copyright.txt in the distribution for a full listing of *
006: * individual contributors. *
007: * *
008: * This is free software; you can redistribute it and/or modify it *
009: * under the terms of the GNU Lesser General Public License as *
010: * published by the Free Software Foundation; either version 2.1 of *
011: * the License, or (at your option) any later version. *
012: * *
013: * This software is distributed in the hope that it will be useful, *
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of *
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
016: * Lesser General Public License for more details. *
017: * *
018: * You should have received a copy of the GNU Lesser General Public *
019: * License along with this software; if not, write to the Free *
020: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA *
021: * 02110-1301 USA, or see the FSF site: http://www.fsf.org. *
022: ******************************************************************************/package org.jboss.portal.registration;
023:
024: import javax.xml.namespace.QName;
025: import java.util.Map;
026:
027: /**
028: * An interface allowing users of the Registration service to customize different aspects of how Consumers are handled.
029: * Methods of this interface are used by RegistrationManager to make appropriate decisions. Implementations of this
030: * interface <strong>MUST</strong> provide a no-argument constructor for instantiation from the class name.
031: *
032: * @author <a href="mailto:chris.laprun@jboss.com">Chris Laprun</a>
033: * @version $Revision: 9177 $
034: * @since 2.6
035: */
036: public interface RegistrationPolicy {
037: /**
038: * Examines and determines whether the given registration properties are adequate for the Consumer associated with
039: * the given identity. This method is called before a Registration is created and thus allows users to decide whether
040: * or not to reject a given registration if not satisfied with the given registration properties.
041: *
042: * @param registrationProperties a Map containing the registration properties in the form of property name (QName) -
043: * property value (Object) mappings
044: * @param consumerIdentity the Consumer identity (as returned by {@link #getConsumerIdFrom(String,
045: * java.util.Map)}) for which the registration properties must be ascertained
046: * @throws IllegalArgumentException if any of the registration properties is invalid for the specified Consumer
047: * @throws RegistrationException if an exception occured in the registration service
048: */
049: void validateRegistrationDataFor(Map registrationProperties,
050: String consumerIdentity) throws IllegalArgumentException,
051: RegistrationException;
052:
053: /**
054: * Generates a registration handle based on the database identity of the Registration. This allows users to customize
055: * the registration handle format if they want to prevent exposure of database-related data.
056: *
057: * @param registrationId the database identity of the Registration for which a handle is required.
058: * @return a registration handle for the Registration associated with the specified identifier.
059: * @throws IllegalArgumentException if the specified registration identity if <code>null</code> or empty
060: */
061: String createRegistrationHandleFor(String registrationId)
062: throws IllegalArgumentException;
063:
064: /**
065: * Determines the ConsumerGroup name to which the Consumer associated with the specified name should be assigned with
066: * or <code>null</code> if the Consumer should not be automatically assigned to a ConsumerGroup. This method is
067: * called during the Consumer creation process to see if the Consumer should be automatically added to a
068: * ConsumerGroup.
069: *
070: * @param consumerName the name of the Consumer being created
071: * @return the name of the ConsumerGroup the Consumer must be automatically added to or <code>null</code> if the
072: * Consumer will not be automatically to a ConsumerGroup at creation
073: * @throws IllegalArgumentException if the specified Consumer name if <code>null</code> or empty
074: */
075: String getAutomaticGroupNameFor(String consumerName)
076: throws IllegalArgumentException;
077:
078: /**
079: * Obtains a consumer identity which uniquely identifies a Consumer in function of the consumer name and registration
080: * properties. This is potentially necessary because Consumer names are not guaranteed to be unique (even though the
081: * specification states that they should).
082: *
083: * @param consumerName the consumer name
084: * @param registrationProperties a Map containing the registration properties in the form of property name (QName) -
085: * property value (Object) mappings. Producer implementations might use the
086: * registration properties to provide secure Consumer identity.
087: * @return the consumer identity
088: * @throws InvalidConsumerDataException if the Policy examines the specified registration properties to determine the
089: * Consumer identity and decides that they are not in a proper state
090: * @throws IllegalArgumentException if the specified Consumer name if <code>null</code> or empty
091: */
092: String getConsumerIdFrom(String consumerName,
093: Map registrationProperties)
094: throws IllegalArgumentException,
095: InvalidConsumerDataException;
096:
097: /**
098: * Determines if the specified Consumer name is acceptable. This method is called before a Consumer is created and
099: * before a unique Consumer identity is created. This is in particular used if the Policy mandates that Consumer
100: * names must be unique.
101: *
102: * @param consumerName the name of the Consumer as passed during the registration process
103: * @throws IllegalArgumentException if the specified Consumer name if <code>null</code> or empty
104: * @throws RegistrationException if an exception occurred in the Registration service
105: */
106: void validateConsumerName(String consumerName)
107: throws IllegalArgumentException, RegistrationException;
108:
109: /**
110: * Determines if the specified ConsumerGroup name is acceptable. This method is called before a ConsumerGroup is
111: * created.
112: *
113: * @param groupName the name of the ConsumerGroup to be created
114: * @throws IllegalArgumentException if the specified ConsumerGroup name if <code>null</code> or empty
115: * @throws RegistrationException if an exception occurred in the Registration service
116: */
117: void validateConsumerGroupName(String groupName)
118: throws IllegalArgumentException, RegistrationException;
119:
120: /**
121: * Retrieves the RegistrationManager with which this RegistrationPolicy is associated.
122: *
123: * @return the RegistrationManager with which this RegistrationPolicy is associated.
124: */
125: RegistrationManager getManager();
126:
127: /**
128: * Associates this RegistrationPolicy with the specified RegistrationManager. This method should not be called
129: * directly by client code as it used in the wiring process of the Registration service.
130: *
131: * @param manager the RegistrationManager with which this RegistrationPolicy should be associated.
132: */
133: void setManager(RegistrationManager manager);
134:
135: /**
136: * Define what the expectations are as far as acceptable registration properties go.
137: *
138: * @param registrationPropertyDescriptions
139: * a map of containing the description of expected registrations
140: * @since 2.6.3
141: */
142: void setExpectations(
143: Map<QName, ? extends PropertyDescription> registrationPropertyDescriptions);
144: }
|