gt: 			String returnText, Map<String, String> getActionState) 
context: /*******************************************************************************
   * Distributed under the terms of the GNU AGPL version 3.
   * Copyright (c) 2011 Glenn Sudduth
   *******************************************************************************/
  package org.aardin.core.api;
  
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  
  import org.aardin.common.exceptions.ServiceException;
  import org.aardin.common.exceptions.ValidationException;
  import org.aardin.common.messaging.ReturnCode;
  import org.aardin.common.model.Partition;
  import org.aardin.common.model.base.PartitionedId;
  import org.aardin.common.server.IRpcService;
  import org.aardin.core.model.Channel;
  import org.aardin.core.model.ChronogramDef;
  import org.aardin.core.model.DefaultMessage;
  import org.aardin.core.model.DeviceClass;
  import org.aardin.core.model.MessageLayout;
  import org.aardin.core.model.NotificationTemplate;
  import org.aardin.core.model.PlanDef;
  import org.aardin.core.model.PartitionConfig;
  import org.aardin.core.model.Subscription;
  import org.aardin.core.model.SubscriptionType;
  import org.aardin.core.model.Tag;
  
  /**
   * Interact with the core notification processor.
   */
  public interface ICoreService 
  	extends IRpcService {
  	
  
  	List<Partition> getPartitions() throws ServiceException;
  	Partition getPartition(String partitionCode) throws ServiceException;
  	
  	/**
  	 * Get the configuration for the given Partition.
  	 */
  	PartitionConfig getPartitionConfig(String partitionCode) throws ServiceException;
  	PartitionConfig saveParitionConfig(PartitionConfig partitionConfig) throws ValidationException, ServiceException;
  	
  	/**
  	 * Channels 
  	 */
  	List<Channel> getChannels(String partitionCode) throws ServiceException;
  	Channel getChannelByCode(String partitionCode, String code) throws ServiceException;
  	Channel	saveChannel(Channel channel) throws ValidationException, ServiceException;
  	void deleteChannel(String partitionCode, String code) throws ServiceException;
  	
  	/**
  	 * Default messages
  	 */
  	List<DefaultMessage> getDefaultMessages(String partitionCode) throws ServiceException;
  	DefaultMessage saveDefaultMessage(DefaultMessage defaultMessage) throws ValidationException, ServiceException;
  	
  	/**
  	 * Tags
  	 */
  	List<Tag> getTags(String partitionCode) throws ServiceException;
  	Tag getTagByCode(String partitionCode, String code) throws ServiceException;
  	Tag saveTag(Tag tag) throws ValidationException, ServiceException;
  	void deleteTag(String partitionCode, String code) throws ServiceException;
  	
  	/**
  	 * Device Classes
  	 */
  	List<DeviceClass> getDeviceClasses() throws ServiceException;
  	DeviceClass getDeviceClassByCode(String name) throws ServiceException;
  	DeviceClass saveDeviceClass(DeviceClass deviceClass) throws ValidationException, ServiceException;
  	
  	/**
  	 * Message Layouts
  	 */
  	List<MessageLayout> getMessageLayouts(String partitionCode) throws ServiceException;
  	MessageLayout getMessageLayout(PartitionedId id) throws ServiceException;
  	MessageLayout saveMessageLayout(MessageLayout messageLayout) throws ValidationException, ServiceException;
  	
  	/**
  	 * Global Plans
  	 */
  	List<PlanDef> getPlans(String partitionCode) throws ServiceException;
  	PlanDef getPlanDefByCode(String partitionCode, String name) throws ServiceException;
  	PlanDef savePlanDef(PlanDef planDef) throws ValidationException, ServiceException;
  	ValidationResults validatePlanXml(String partitionCode, String xml) throws ServiceException;
  	
  	/**
  	 * Validates a personal notification plan as an XML document.
  	 * <br/>
  	 * Personal notification plans definitions are AccountService entities, but validation occurs here because
  	 * the parser, referenced entities, etc. reside within CoreService.
  	 * @param xml A personal notification definition.
  	 * @throws ValidationException if the document is not valid in terms of structure or the entities it references.
  	 * @throws ServiceException if something goes wrong with the request.
  	 */
  	ValidationResults validatePersonalNotificationPlanXml(String partitionCode, String xml) throws ServiceException;
  
  	/**
  	 * Global Chronograms
  	 */
  	List<ChronogramDef> getChronograms(String partitionCode) throws ServiceException;
  	ChronogramDef getChronogramDefByCode(String partitionCode, String name) throws ServiceException;
  	ChronogramDef saveChronogramDef(ChronogramDef chronogramDef) throws ValidationException, ServiceException;
  	ValidationResults validateChronogramXml(String partitionCode, String xml) throws ServiceException;
  	
  	/**
  	 * Gets a list of {@link Subscription}s for the given channel.
  	 * @param code The code of the channel.
  	 * @return A List of user names.
  	 */
  	List<Subscription> getChannelSubscriptions(String partitionCode, String code) throws ServiceException;
  	
  	/**
  	 * Gets a list of {@link Subscriptions}s for to the given notification template.
  	 * @return A List of user names.
  	 */
  	List<Subscription> getNotificationTemplateSubscriptions(String partitionCode, String code) throws ServiceException;
  	
  	/**
  	 * Subscribes a {@link Responder} to a channel or notification template. 
  	 * 
  	 * @param partition The partition of the entities.
  	 * @param userName The user name of the responder.
  	 * @param type Indicates whether the subscription is for a Channel or a NotificationTemplate.
  	 * @param subjectCode The code of the entity that's being subscribed to. This will be used to find the Partition of the user.
  	 */          
  	Subscription createSubscription(String partitionCode, String username, SubscriptionType type, String subjectCode) throws ServiceException;
  	
  	/**
  	 * Gets all {@link Subscription}s for a particular {@link Responder}.
  	 * @param userName The responder's user name.
  	 * @return A list of Subscriptions.
  	 * @throws ServiceException
  	 */
  	List<Subscription> getSubscriptions(String partitionCode, String username) throws ServiceException;
  	
  	/**
  	 * Deletes a subscription. 
  	 * @param id The id of the subscription.
  	 */
  	void deleteSubscription(String partitionCode, String code) throws ServiceException;
  	
  	/**
  	 * Deletes all {@link Subscription}s for a particular {@link Responder}. This would be called when a responder is 
  	 * deleted.
  	 * @param userName The user name of the responder.
  	 * @throws ServiceException
  	 */
  	int deleteSubscriptions(String partitionCode, String username) throws ServiceException;
  
  	/**
  	 * 
  	 * Everything from here down is related to notification processing.
  	 * 
  	 *  TODO: Move server config / admin methods to a ICoreAdminConfigService IConfigurationService or maybe extend this interface.
  	 */
  	//NotificationTemplate getNotificationTemplate(PartitionedId id) throws ServiceException;
  	NotificationTemplate getNotificationTemplateByCode(String partitionCode, String code) throws ServiceException;
  	List<NotificationTemplate> getNotificationTemplates(String partitionCode) throws ServiceException;
  	NotificationTemplate saveNotificationTemplate(NotificationTemplate notificationTemplate) throws ValidationException, ServiceException;
  	void deleteNotificationTemplate(String partitionCode, String code) throws ServiceException;
  	
  	
  	/**
  	 * Gets a list of all active Notifications.
  	 * @return
  	 * @throws ServiceException
  	 */
  	Set<INotification> getNotifications(String partitionCode) throws ServiceException;
  	
  	/**
  	 * Gets a Notification by Id.
  	 * 
  	 * @param notificationId
  	 * @return
  	 */
  	INotificationData getNotification(String partitionCode, String notificationId) throws ServiceException;
  	
  	/**
  	 * Get notifications where a particular user has been notified.
  	 * @param userName The user name of the responder.
  	 * @return A list of notifications. An empty list is returned if none are found.
  	 * @throws ServiceException
  	 */
  	Set<INotification> getNotificationsForResponder(String partitionCode, String userName) throws ServiceException;
  	
  	/**
  	 * Initiates a notification.
  	 * 
  	 * @param notificationInfo
  	 * @return The ID of the notification.
  	 * @throws ServiceException
  	 */
  	String initiateNotification(String partitionCode, String notificationTemplateCode, Map<String, String> notificationParameters) 
  		throws ServiceException;
  	
  	/**
  	 * Initiates a notification with blame support.
  	 * 
  	 * @param notificationTemplateCode The code of the notification template
  	 * @param notificationParameters The notification parameters.
  	 * @param username The username of the person initiating the notification.
  	 * @return The ID of the notification.
  	 * @throws ServiceException
  	 */
  	String initiateNotification(String partitionCode, String notificationTemplateCode, Map<String, String> notificationParameters, String username) 
  		throws ServiceException;
  	
  	/**
  	 * Acknowledge a notification.
  	 * 
  	 * @param notificationId - The ID of the notification to acknolowledge.
  	 * @param username - The username of the person acknolowledging the event.
  	 * @param ingoreDups - A period in which to ignore duplicate notifications.
  	 */
  	void acknowledgeNotification(String partitionCode, String notificationId, String username, String ignoreDups) 
  		throws ServiceException;
  	
  	/**
  	 * Acknowledge a notification. The event will use the default ignore period.
  	 * 
  	 * @param notificationId - The ID of the notification to acknolowledge.
  	 * @param username - The username of the person acknolowledging the event.
  	 */
  	void acknowledgeNotification(String partitionCode, String id, String string) 
  			throws ServiceException;
  	
  	/**
  	 * Cancel a notification by Id. A cancel (formerly "recover") occurs when the state
  	 * of the subject of the notification returns to normal. All addresses which received messages
  	 * indicating the notification was active will receive a message indicating the notification
  	 * is no longer active.  
  	 * 
  	 * @param notifcationId The ID of the notification to cancel. 
  	 */
  	void cancelNotification(String partitionCode, String notifcationId) throws ServiceException;
  	
  	/**
  	 * Cancel a notification using template name and parameters.
  	 * 
  	 * @param notificationTemplateName The name of the notifiation template.
  	 * @param notificationParameters The required parameters for the notifiation.
  	 */
  	void cancelNotification(String partitionCode, String notificationTemplateName, Map<String, String> notificationParameters) 
  		throws ServiceException;
  	
  	/**
  	 * Terminate a notification. A terminated notivication will simply disappear without
  	 * performing any further actions.
  	 * 
  	 * @param notifcationId The ID of the notification to terminate. 
  	 * @param username The username of the person who initiated the request.
  	 */
  	void terminateNotification(String partitionCode, String notifcationId, String username) throws ServiceException;
  	
  	
  	/**
  	 * Handler for asynchronous responses from the Action service.
  	 */
  	void handleActionResponse(String partitionCode, String notificationId, String requestUUID, ReturnCode returnCode, 
  