Properties p = new Properties();
p.setProperty("server.name", "webserver1");
p.setProperty("server.alias", "Application XYZ");
p.setProperty("config.servers", "loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false");
Agent.setProperties(p);

-Dserver.name=webserver1 -Dconfig.servers=loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false

server.name=webserver1
server.alias=Application XYZ
config.servers=loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false

package dk.itp.security.passticket;

import java.io.IOException;
import java.io.Serializable;
import java.util.List;
import java.util.Properties;

import dk.itp.managed.service.client.INotificationListener;
import dk.itp.managed.service.client.NotificationReply;
import dk.itp.security.authorization.client.ACLEntry;
import dk.itp.security.authorization.client.GroupEntry;
import dk.itp.security.authorization.client.URLEntry;
import dk.itp.security.authorization.client.UserEntry;
import dk.itp.security.exception.ConfigurationException;
import dk.itp.statistics.Statistics;
import dk.portalprotect.geolocator.LocatorInfo;

/**
 * Interface to the passticket server - this interface is a clients only access to the
 * passticket server / session controller - the implementation is hidden in another class.
 * 
 * <pre>
 * PortalProtect - Security infrastructure
 * Copyright(c) 2001, IT Practice A/S, All rights reserved.
 * 
 * This source code is confidential.
 * </pre>
 */
public interface IPTServer {
	public static final String CHANNEL_UNKNOWN = "00";
	public static final String CHANNEL_HTTP = "01";
	public static final String CHANNEL_SSL = "02";
	public static final String CHANNEL_SCL = "03";
	public static final String CHANNEL_USERDEFINED = "04";

	public static final short PERMISSION_WRONG_CHANNEL_USE_HTTP = 1;
	public static final short PERMISSION_WRONG_CHANNEL_USE_SSL = 2;
	public static final short PERMISSION_WRONG_CHANNEL_USE_SCL = 3;
	public static final short PERMISSION_NOT_FOUND = 4;

	/**
	 * Returns the "current" configuration for the PT server agent.
	 * @return Properties configuration of the PT agent.
	 * @throws ConfigurationException If some error occurs while getting the configuration, this exception is thrown
	 */
	public Properties getConfiguration() throws ConfigurationException;

	/**
	 * Returns the configuration for the specified server.
	 * @param serverName Name of server to retrieve configuration for
	 * @return Properties configuration of the specified server.
	 * @throws ConfigurationException If some error occurs while getting the configuration, this exception is thrown
	 */
	public Properties getConfiguration(String serverName) throws ConfigurationException;

	/**
	 * Adds another listener that will be notified if user logs on or off
	 * @param listener The PTListener Listener
	 */
	public void addPTListener(PTListener listener);

	/**
	 * Changes the users password
	 * @param sessionID
	 * @param oldPassword
	 * @param newPassword
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void changePassword(String sessionID, String oldPassword, String newPassword) throws PTException;

	/**
	 * Checks a given acl (Access Control List)
	 * @param sessionID Session ID
	 * @param aclName ACL name to check
	 * @return true if check was ok, false if access was denied
	 * @throws AclNotFoundException This is thrown if no ACL was found with the specified name.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean checkPermission(String sessionID, String aclName) throws PTException;

	/**
	 * Checks a given acl (Access Control List)
	 * @param sessionID Session ID
	 * @param aclName ACL Name
	 * @param additionalData Additional data that might be required to do the permission check, such as data-based authorization
	 * @return true if check was ok, false if access was denied
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean checkPermission(String sessionID, String aclName, Object additionalData) throws PTException;

	/**
	 * Checks a given acl (Access Control List)
	 * @param sessionID Session ID
	 * @param identifier Identifier of the ACL - used to separate ACLs e.g. between applications, use null for default.
	 * @param aclName ACL Name
	 * @param additionalData Additional data that might be required to do the permission check, such as data-based authorization
	 * @return true if check was ok, false if access was denied
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean checkPermission(String sessionID, String identifier, String aclName, Object additionalData) throws PTException;

	/**
	 * Deletes a state variable from the session
	 * @param sessionID Session ID
	 * @param key Key to delete
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void deleteStateVariable(String sessionID, String key) throws PTException;

	/**
	 * Returns a specific ACL entry for the given identifier.
	 * @param aclName The name of the ACL to retrieve
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @throws PTException This is thrown if some error occurs.
	 */
	public ACLEntry getACL(String aclName, String identifier) throws PTException;

	/**
	 * Returns a specific Group entry for the given identifier.
	 *
	 * @param groupName The name of the group to retrieve
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @throws PTException This is thrown if some error occurs.
	 */
	public GroupEntry getGroup(String groupName, String identifier) throws PTException;

	/**
	 * Returns all known ACLs for the given identifier.
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @return ACLEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public ACLEntry[] getAvailableACLs(String identifier) throws PTException;

	/**
	 * Returns all known groups for the given identifier.
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @return GroupEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public GroupEntry[] getAvailableGroups(String identifier) throws PTException;

	/**
	 * Returns known users for the given criterias.<br>
	 * Note that this method is most suited for exposing known users to an administration interface, like weblogics portal administration.
	 * @param wildcard The wildcard to match, could be * or part of the username/id
	 * @param groupName If not null, searches for users within the specified group
	 * @param searchSpec Additional search parameters, can be used for limiting searches if not null
	 * @param maxReturns Maximum number of user entries to return
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @param authorizationType Type of authorization plugin, or 0 to use default
	 * @return UserEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public UserEntry[] getAvailableUsers(String wildcard, String groupName, String searchSpec, int maxReturns, String identifier, int authorizationType) throws PTException;

	/**
	 * Returns the type of this channel - see the CHANNEL_* constants
	 * @param sessionID Session ID
	 * @return String channel type behind session id (transaction)
	 */
	public String getChannelType(String sessionID);

	/**
	 * Returns the CICS password to use for a particular session ID
	 * @param sessionID Session ID
	 * @return String CICS password, behind user behind sessionid
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getCICSPassword(String sessionID) throws PTException;

	/**
	 * Returns the CICS userid to use for this session
	 * @param sessionID Session ID
	 * @return CICS user behind user behind session id 
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getCICSUser(String sessionID) throws PTException;

	/**
	 * Return the customer number, if this user is logged on
	 * @param sessionID Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getCustomerID(String sessionID) throws PTException;

	/**
	 * Return the agreement number, if this user is logged on
	 * @param sessionID Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getAgreementID(String sessionID) throws PTException;

	/**
	 * Returns the password (or null) for the user if he is logged on
	 * @param sessionID Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getPassword(String sessionID) throws PTException;

	/**
	 * Get a state variable from the session
	 * @param sessionID Session ID
	 * @param key Key to retrieve value for
	 * @return StateVariable
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getStateVariable(String sessionID, String key) throws PTException;

	/**
	 * Gets the list of state variable keys from the session
	 * @param sessionID Session ID
	 * @return Array of state variable keys
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String[] getStateVariableKeys(String sessionID) throws PTException;
	
	/**
	 * Returns the id of the user associated with the given session id
	 * @param sessionID Session ID
	 * @return user behind session id
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getUser(String sessionID) throws PTException;

	/**
	 * Returns the IP address that the user is believed to have.<br><b>Note:</b> This IP is the one that was used when the
	 * session was created, and if IP checking in the dispatcher is disabled the current request might or might not
	 * have another IP address. In this case, configure the dispatcher to forward the Users IP address in an HTTP
	 * header, and rely on this instead for every current request.
	 * 
	 * @param sessionID Session ID
	 * @return user IP address behind session id
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getUserIP(String sessionID) throws PTException;

	/**
	 * Returns the name of the user associated with the session, or null if the name is not available.
	 * @param sessionID Session ID
	 * @return user name behind sessionid
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getUserName(String sessionID) throws PTException;

	/**
	 * Returns true if this is an "internal" or intranet user, false if it is an internet user
	 * @param sessionID Session ID
	 * @return true is user behind sessionid is an 'internal' user, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isInternalUser(String sessionID) throws PTException;

	/**
	 * Checks to see if a user is logged or, or if he is anonymous
	 * @param sessionID Session ID
	 * @return true is user behind sessionid is logged on, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isLoggedOn(String sessionID) throws PTException;

	/**
	 * Gets the authentication level for a user
	 * @param sessionID Session ID
	 * @return The authentication level of the user, which is 0 if he is not logged in
	 * @throws PTException This is thrown if some error occurs.
	 */
	public int getAuthenticationLevel(String sessionID) throws PTException;

	/**
	 * Gets the authentication method for a user. The methods are in the <code>AuthTypes</code> interface.
	 * @param sessionID Session ID
	 * @return The authentication method of the user, which is 0 if he is not logged in.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public int getAuthenticationMethod(String sessionID) throws PTException;

	/**
	 * Returns true/false depending on wether a given session is valid
	 * @param sessionID Session ID
	 * @return boolean true if session id is valid, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isValid(String sessionID);

	/**
	 * The user associated with this session will be logged off, note that the session itself is not removed until removeSession is called.
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logoff(String sessionId) throws PTException;

	/**
	 * The user associated with this session will be logged off after a certain delay (specified on the server)
	 * If the session is still active within the delay timeout, the logoff will be cancelled, and the session will
	 * continue. It is meant to be used when switching between multiple domains, and in situations where automatic
	 * logoff will cause problems, like refreshing pages or resizing in netscape.
	 * 
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void delayedLogoff(String sessionId) throws PTException;

	/**
	 * Cancels a pending delayed logoff.
	 * 
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void cancelDelayedLogoff(String sessionId) throws PTException;

	/**
	 * Checks if this session is waiting for a delayed logoff
	 * 
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 * @return True if this session is about to be the victim of a delayed logoff, false otherwise
	 */
	public boolean isDelayedLogoff(String sessionId) throws PTException;

    /**
     * Issue new cryptograpic token for SSO to other systems. This request will be delegated to the specificed AuthenticationPlugin.
     * @param sessionId Session ID
     * @param authType
     * @throws PTException
     */
    public String newToken(String sessionId, int authType) throws PTException;

    /**
     * Issue new cryptograpic token for SSO to other systems. This request will be delegated to the specificed AuthenticationPlugin.
     * @param sessionid Session ID
     * @param authType
     * @param inputToken
     * @throws PTException
     */
    public String newToken(String sessionid, int authType, String inputToken) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType Authentication plugin type - @see AuthTypes
	 * @param user
	 * @param credentials
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, String user, Object credentials) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param credentials it is assumed that crendetials object contains userid and plugin knows how to 
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, Object credentials) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param user
	 * @param password
	 * @param newPassword
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, String user, Object password, Object newPassword) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param user
	 * @param password
	 * @param newPassword
	 * @param timeout Timeout in milliseconds for login to complete - set to 0 or -1 for default.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, String user, Object password, Object newPassword, long timeout) throws PTException;

	/**
	 * Logs a user on with the specified userid and password - the session must be created first
	 * @param sessionId Session ID
	 * @param user
	 * @param password
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, String user, String password) throws PTException;

	/**
	 * Logs a user on with the specified userid, password and new password - the session must be created first
	 * @param sessionId Session ID
	 * @param password
	 * @param newPassword
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, String user, String password, String newPassword) throws PTException;

	/**
	 * Logs a user on with the specified userid, password and new password - the session must be created first
	 * @param sessionId Session ID
	 * @param password
	 * @param newPassword
	 * @param timeout Timeout in milliseconds for login to complete - set to 0 or -1 for default.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, String user, String password, String newPassword, long timeout) throws PTException;

	/**
	 * Provides support for confirmations (which usually means digital signatures) - a confirmation can just be
	 * a reauthentication, but usually it will be a digital signed request, which is then checked.
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param signtext
	 * @param credentials
	 * @return true if the confirmation succeeds, which means that either the digital signature was correct, or the reauthentication succeeded.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean confirm(String sessionId, int authType, String signtext, Object credentials) throws PTException;

	/**
	 * Provides support for confirmations (which usually means digital signatures) - a confirmation can just be
	 * a reauthentication, but usually it will be a digital signed request, which is then checked.
	 * @param sessionId
	 * @param authType @see AuthTypes
	 * @param credentials it is assumed that credentials object contains signtext and plugin knows how to get it.
	 * @return true if the confirmation succeeds, which means that either the digital signature was correct, or the reauthentication succeeded.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean confirm(String sessionId, int authType, Object credentials) throws PTException;

	/**
	 * This method measures the amount of time an operation took.
	 * The statistics is sent to the statistics/config server, which then creates nice graphics and
	 * creates summaries.
	 *
	 * @param name The name of the operation
	 * @param time The number of miliseconds it took
	 */
	public void measureStatistics(String name, long time);

	/**
	 * Creates a new session
	 * @param clientIP Client IP Address
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String newSession(String clientIP) throws PTException;

	/**
	 * Creates a new session, and lets the system know what session ID the user previously had
	 * @param clientIP Client IP Address
	 * @param oldSessionID Old session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String newSession(String clientIP, String oldSessionID) throws PTException;

	/**
	 * Creates a new session, with the specified session ID, and lets the system know what session ID the user previously had
	 * @param clientIP Client IP Address
	 * @param requestedSessionID The session ID this session should have. 
	 * @param oldSessionID Old session ID, if changing sessions e.g. between http and https
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String newSession(String clientIP, String requestedSessionID, String oldSessionID) throws PTException;

    /**
     * Creates a new session, with the specified session ID, and lets the system know what session ID the user previously had
     * @param clientIP Client IP Address
     * @param requestedSessionID The session ID this session should have. 
     * @param oldSessionID Old session ID, if changing sessions e.g. between http and https
     * @param segmentId Segment ID between 0 and 255 - the session will be created with the specified segment ID
     * @throws PTException This is thrown if some error occurs.
     */
    public String newSession(String clientIP, String requestedSessionID, String oldSessionID, short segmentId) throws PTException;
    
    /**
     * Creates a new session, with the specified session ID, and lets the system know what session ID the user previously had
     * @param clientIP Client IP Address
     * @param requestedSessionID The session ID this session should have. 
     * @param oldSessionID Old session ID, if changing sessions e.g. between http and https
     * @param segmentId Segment ID between 0 and 255 - the session will be created with the specified segment ID
     * @param clusterID Cluster ID of the session controller cluster to create the session in.
     * @throws PTException This is thrown if some error occurs.
     */
    public String newSession(String clientIP, String requestedSessionID, String oldSessionID, short segmentId, int clusterID) throws PTException;
    
	/**
	 * Removes a previously defined listener
	 * @param listener PTListener Listener
	 */
	public void removePTListener(PTListener listener);

	/**
	 * Removes a session from the list of active sessions
	 * @param sessionID The session ID to remove
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void removeSession(String sessionID) throws PTException;

	/**
	 * Sets a state variable that is kept in the session
	 * @param sessionID The session ID to lookup
	 * @param key The name of the state variable
	 * @param value The value of the state variable
	 * @param persistent True if the state variable should be considered persistent (saved to user-repository via authentication plugin, if possible)
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void setStateVariable(String sessionID, String key, String value, boolean persistent) throws PTException;

	/**
	 * Sets multiple state variables that is kept in the session
	 * @param sessionID The session ID to lookup
	 * @param keyValues A map of String keys with String values that are to be stored (or removed if the value is null)
	 * @param persistent True if the state variable should be considered persistent (saved to user-repository via authentication plugin, if possible)
	 * @throws PTException This is thrown if some error occurs.
	 * @since 6.0.1
	 */
	public void setStateVariables(String sessionID, Map<String,String> keyValues, boolean persistent) throws PTException;

	/**
	 * Check if the session/user is member of a group
	 * @param sessionID The session ID to lookup
	 * @param group The name of the group to check if the session or user belongs to
	 * @return True if the user is member og this group.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isMemberOfGroup(String sessionID, String group) throws PTException;

	/**
	 * Checks if access to the specified URL is allowed for this session
	 * @param sessionID The session ID to lookup
	 * @param identifier The identifier of the server the user is trying to access
	 * @param url The URL to check
	 * @return boolean true if URL is allowed, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isURLAllowed(String sessionID, String identifier, String url) throws PTException;

	/**
	 * Checks if access to the specified URL is allowed for this session
	 * @param sessionID The session ID to lookup
	 * @param identifier The identifier of the server the user is trying to access
	 * @param url The URL to check
	 * @param method HTTP Method
	 * @return boolean true if URL is allowed, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isURLAllowed(String sessionID, String identifier, String method, String url) throws PTException;
	
	/**
	 * Retrieves the list of URL protection entries
	 * @param identifier
	 * @return URLEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public URLEntry[] getProtectedURLs(String identifier) throws PTException;

	/**
	 * Returns an encrypted session cookie, which safely is sent to the target partner server, even
	 * in unencrypted form, since it is encrypted with the servers private key, and the target
	 * servers public key.
	 * 
	 * @param sessionID The session ID to convert to an encrypted cookie
	 * @param url The URL to redirect to at the server, once the cookie has arrived
	 * @param sourceName The name of the source (this server), the name is used to find the proper private key
	 * @param targetName The name of the target server this request is sent to, the name is used to find the correct public key
	 * @return The encrypted cookie contents
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getEncryptedSessionCookie(String sessionID, String url, String sourceName, String targetName) throws PTException;

	/**
	 * Decrypts a received encrypted session cookie
	 * 
	 * @param cookie The data to decrypt
	 * @param sourceName The name of the source (this server), the name is used to find the proper private key
	 * @param targetName The name of the target server this request is sent to, the name is used to find the correct public key
	 * @return The decrypted contents
	 * @throws PTException This is thrown if some error occurs.
	 */
	public DataExchangeCookie decryptEncryptedSessionCookie(String cookie, String sourceName, String targetName) throws PTException;

	/**
	 * Logs an event to the transaction log.<br>
	 * Note that this is only relevant when the user is logged on, and if the authentication plugin on the server supports
	 * transaction logs.
	 * 
	 * @param sessionID The session ID to lookup
	 * @param context The context this is logged in, which is a text identifying the business area that originated this.
	 * @param text The text to log
	 * @param signed If true, the request was probably signed, which means that it should also exist in a non-repudiation log.
	 * @throws PTException if the session cannot be found, or if no user is logged on.
	 */
	public void logToTransactionLog(String sessionID, String context, String text, boolean signed) throws PTException;

	/**
	 * Return the server name of this instance (found in PTServer.properties or in environment variable server.name
	 * 
	 * @return String server name, found in ptserver.properties
	 */
	public String getName();
	
	/**
	 * Adds a configuration listener that will be called if the configuration is set or changed.
	 *  
	 * @param listener The listener to add
	 */	
	public void addConfigListener(IConfigListener listener);
	
	/**
	 * Removes a previously added configuration listener
	 *  
	 * @param listener The listener to remove
	 */	
	public void removeConfigListener(IConfigListener listener);

	/**
	 * Adds a status text provider, which can provide an html formatted text snippet of status text that will be shown in PP's status
	 * for this server
	 * @param provider The IStatusTextProvider to add
	 */	
	public void addStatusTextProvider(IStatusTextProvider provider);
	
	/**
	 * Removes a previously added status text provider
	 * @param provider The provider to remove
	 */
	public void removeStatusTextProvider(IStatusTextProvider provider);
	
	/**
	 * Sets the specific status text provider for the specified action
	 * @param name Action name
	 * @param provider Status text provider
	 */
	public void addSpecificStatusTextProvider(String name, IStatusTextProvider provider);
		
	/**
	 * Can be used to obtain the statistics element used by this server
	 */
	public Statistics getStatistics();
	
	/**
	 * Return a list of ACL names that the specified user currently has
	 *  
	 * @param sessionID Session ID
	 * @return array of acl names
	 * @throws PTException
	 */
	public String[] getUserACLs(String sessionID) throws PTException;

	/**
	 * Return a list of group names that the specified user currently has
	 *  
	 * @param sessionID Session ID
	 * @return array of group names
	 * @throws PTException
	 */
	public String[] getUserGroups(String sessionID) throws PTException;

	/**
	 * Validates a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param credentials it is assumed that crendentials object contains userid and plugin knows how to 
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void validate(String sessionId, int authType, Object credentials) throws PTException;

	/**
	 * Validates a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void validate(String sessionId, int authType, String user, Object password ) throws PTException;

	/**
	 * Validates a user on with the specified userid and password - the session must be created first
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void validate(String sessionId, String user, String password) throws PTException;

	/**
	 * Generates a cross domain session object that can be transferred 
	 * @param sessionID
	 * @param fromDomain
	 * @param toDomain
	 * @return The cross domain session controller string
	 * @throws PTException
	 */
    public String getCrossDomainSession( String sessionID, String fromDomain, String toDomain ) throws PTException;
    
    /**
     * Asks the authentication plugin to execute an arbitrary command, on the authentication plugin that the user
     * within the session is currently logged into.
     * 
     * @param sessionID Session ID
     * @param name Name of command to execute, depends on the specific plugin.
     * @param input Input object (must be serializable)
     * @return Output object (must be serializable)
     * @throws PTException If an error occurs
     */
    public Object executeAuthpluginCommand(String sessionID, String name, Object input) throws PTException;

    /**
     * Asks the authentication plugin to execute an arbitrary command.
     * 
     * @param sessionID Session ID
     * @param name Name of command to execute, depends on the specific plugin.
     * @param authType Authentication plugin to send this to
     * @param input Input object (must be serializable)
     * @return Output object (must be serializable)
     * @throws PTException If an error occurs
     */
    public Object executeAuthpluginCommand(String sessionID, int authType, String name, Object input) throws PTException;

    /**
     * Returns the name of the agent which created the session, or null if not available.
     * 
     * @param sessionID Session ID
     * @return Name of agent which created the session, or null if not available.
     * @throws PTException If an error occurs
     */
    public String getNameOfCreatingAgent(String sessionID) throws PTException;
    
    /**
     * Persist the content of a session to a string which can be saved for later, and passed to restorePersistedSession
     * to restore the session contents to memory.
     * 
     * @param sessionID Session ID of the user requesting the persisting to be done
     * @param sessionIDToPersist Session ID to persist
     * 
     * @return The session ID of the persisted session.
     * @throws PTException If an error occurs
     */
    public String persistSession(String sessionID, String sessionIDToPersist) throws PTException;
    
    /**
     * Restores a previously persisted session to memory, from the persisted
     * @param sessionID Session ID of user restoring the session - restoring a session might require special permissions
     * @param persistedSessionData Session Data previously persisted
     * 
     * @return The session ID of the restored session.
     * @throws PTException If an error occurs
     */
    public String restorePersistedSession(String sessionID, String persistedSessionData) throws PTException;
    
    /**
     * Can be used to change the alias name of this agent - The alias is shown next to the server name in the Admin
     * GUI.
     * @param alias The new alias to use
     */
    public void setAlias(String alias);
    
    /**
     * Sends an async notification to one or more servers.
     * 
     * @param serverNamePattern Pattern matching one or more servers (e.g. *session*) or null to match any server.
     * @param serverTypePattern Pattern matching one or more server types, e.g. *agent) or null for any server
     * @param notificationName Notification name - a name for this notification event.
     * @param notificationObject Notification object, data sent along with the notification name
     */
    public void sendNotification(String serverNamePattern, String serverTypePattern, String notificationName, Serializable notificationObject) throws IOException;
    
    /**
     * Sends a synchronous notification to one or more servers, and expect a reply to it
     * 
     * @param serverNamePattern Pattern matching one or more servers (e.g. *session*) or null to match any server.
     * @param serverTypePattern Pattern matching one or more server types, e.g. *agent) or null for any server
     * @param notificationName Notification name - a name for this notification event.
     * @param notificationObject Notification object, data sent along with the notification name
     */
    public NotificationReply sendNotificationWithReply(String serverNamePattern, String serverTypePattern, String notificationName, Serializable notificationObject) throws IOException;
    
    /**
     * Adds a notification listener which will be called whenever a notification has arrived.
     * 
     * @param listener Listener to add
     */
    public void addNotificationListener(INotificationListener listener);
    
    /**
     * Removes a previously added notification listener.
     * 
     * @param listener Listener to remove
     */
    public void removeNotificationListener(INotificationListener listener);
    
    /**
     * Looks up GeoIP information based on an IP address. Note that the accuracy of the information depends on the
     * libraries purchased from MaxMind.
     * 
     * @param ip IP address to lookup
     * @return LocatorInfo Locator information
     * @throws PTException If an error occurs
     */
    public LocatorInfo lookupGeoIP(String ip) throws PTException;
    
    /**
     * Obtain a Session based upon a ticket, the ticket could be a previously issued OAuth ticket, or something
     * entirely different depending on your authentication plugin.
     * The ticket must be unique across authentication plugins, and the agent caches sessions based upon the ticket
     * so there are no penalties for repeated calls to this method with the same ticket id.
     * 
     * @param ticket Earlier issued ticket
	 * @param authType @see AuthTypes
	 * @param segmentId Segment ID of dispatcher, or 0
	 * @param clusterId Cluster ID, or 0 for default
	 * @param clientIP The client IP address
     * @return Session ID
     * @throws PTException If an error occurs
     */
    public String getSessionFromTicket(int authType, String ticket, short segmentId, short clusterId, String clientIP) throws PTException;
    
    /**
     * Obtain a Session based upon a ticket, the ticket could be a previously issued OAuth ticket, or something
     * entirely different depending on your authentication plugin.
     * The ticket must be unique across authentication plugins, and the agent caches sessions based upon the ticket
     * so there are no penalties for repeated calls to this method with the same ticket id, unless no session exists - in that case, every call will be a remote call to the sessioncontroller.
     * If the a session does not exist already, null will be returned - if a session exists, the ID of it will be returned.
     * 
     * @param ticket Earlier issued ticket for which a session exists, created using getSessionFromTicket(authType, ticket, segmentId, clusterId, clientIP)
	 * @param clusterId Cluster ID, or 0 for default
     * @return Session ID or null if no session for this ticket currently exists
     * @throws PTException If an error occurs
     */
    public String getSessionFromTicket(String ticket, int clusterId) throws PTException;
    
    /**
     * Get the ticket, e.g. OAuth Bearer token stored within the session, or null if no ticket exists.
     * 
     * @param sessionid Session ID
     * @throws PTException If an error occurs
     * @return Ticket or null if no ticket exists for the session
     */
    public String getTicketFromSession(String sessionid) throws PTException;
    
    /**
     * Returns a list of session IDs for which the supplied user is authenticated within. This can be used to find
     * active sessions for a given user and perform some action upon them. 
     * 
     * @param userid Userid to look for in list of authenticated sessions
     * @return List of session IDs where this user is authenticated
     * @throws PTException If an error occurs
     */
    public List<String> getSessionsWhereUserIsAuthenticated(String userid) throws PTException;


    /**
     * Updates the ticket within a session, changing the ticket to the new value
     * 
     * @param sessionid Session ID
     * @param ticket New ticket
     * @throws PTException If an error occurs
     */
    public void updateTicketInSession(String sessionid, String ticket) throws PTException;
}