jet.server.api.http

Interface HttpUserSessionManager

All Superinterfaces:

UserSessionManager

public interface HttpUserSessionManager
extends UserSessionManager

HttpUserSessionManager is an extended interface of UserSessionManager for HTTP protocol.
This class provides methods that manage the UserSession within the servlet container.
The UserSession holds state related to a logged-in user across HTTP requests. It is stored in the servlet session.
A user is logged-in to JReport Server by a call to checkLogin() or checkAdminLogin() and is logged out by call to logout().

Method Summary

Modifier and Type	Method and Description
boolean	checkAdminLogin(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, java.lang.String realm, java.util.Properties query) Performs an authentication check for the current HTTP Request looking for an admin user.
boolean	checkAdminLogin(javax.servlet.http.HttpServletRequest req, java.lang.String realm, java.util.Properties query) Deprecated. This method has been deprecated since V8. You should use its overloaded method checkAdminLogin(req, res, realm, query), if you want to provide a special extra channel feature for admin user.
boolean	checkAdminLoginEx(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, java.lang.String realm, java.util.Properties query) Performs an authentication check for the current HTTP Request looking for an admin user.
boolean	checkLogin(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, java.lang.String realm, java.util.Properties query) Performs an authentication check for the current HTTP Request.
boolean	checkLogin(javax.servlet.http.HttpServletRequest req, java.lang.String realm, java.util.Properties query) Deprecated. This method has been deprecated since V8. You should use its overloaded method checkLogin(req, res, realm, query), if you want to provide a special extra channel feature for admin user.
boolean	checkLoginEx(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, java.lang.String realm, java.util.Properties query) Performs an authentication check for the current HTTP Request.
HttpExternalAuthorized	getHttpExternalAuthorized() Gets the HttpExternalAuthorized class that is registered to be used by checkLogin().
java.lang.String	getUser(javax.servlet.http.HttpServletRequest req) Gets the user ID (user name) of the logged-in user for the web session, based on the UserSession object stored in the servlet session related to the HttpServletRequest.
UserSession	getUserSession(javax.servlet.http.HttpServletRequest req) Gets the JReport Server UserSession object associated with the logged-in user for the web session.
boolean	isExtraChannel(javax.servlet.http.HttpServletRequest req) Checks whether the current HTTP Request is associated with a logged-in user session that was allowed to login under the special extra channel situation.
UserSession	loginMD5(java.lang.String realm, java.lang.String userID, java.lang.String digestResponse, java.lang.String unquotedNonce, java.lang.String digestURI, java.lang.String httpMethod, java.lang.Object extObj) Logs in a user with the digest MD5 method.
UserSession	loginMD5(java.lang.String realm, java.lang.String userID, java.lang.String digestResponse, java.lang.String unquotedNonce, java.lang.String digestURI, java.lang.String httpMethod, java.lang.Object extObj, boolean isWait) Logs in a user with the digest MD5 method.
void	logout(javax.servlet.http.HttpServletRequest req) Logs out the JReport Server user who is currently logged into the web session.
void	removeExpiredUserSessions(javax.servlet.http.HttpServletRequest req) Removes the expired user sessions (exceeding the max inactive interval).
void	sendUnauthorizedResponse(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, java.lang.String authScheme, java.lang.String realm) Sends an HTTP unauthorized response (HTTP 401) to the client.
void	setHttpExternalAuthorized(HttpExternalAuthorized externalAuthorized) Sets the HttpExternalAuthorized class that will be used by checkLogin() to authenticate a user for the session.

Methods inherited from interface jet.server.api.UserSessionManager

addSessionExpiryListener, getAllUserSessions, getAllWaitUserSessions, getAuthenticator, getDefaultMaxInactiveInterval, getLastLoginTime, getLastLogoutTime, getUserSession, isWait, login, loginExternalAuthorized, logout, needSecurity, putSessions, refreshLastAccessTime, removeSessionExpiryListener, setAuthenticator, setDefaultMaxInactiveInterval, updateUserSession

Method Detail

getUser

java.lang.String getUser(javax.servlet.http.HttpServletRequest req)

Gets the user ID (user name) of the logged-in user for the web session, based on the UserSession object stored in the servlet session related to the HttpServletRequest.

Parameters:

req - the HttpServletRequest.

Returns:

the user ID of the logged-in user for the current session. Returns an empty string when no user is logged-in.

getUserSession

UserSession getUserSession(javax.servlet.http.HttpServletRequest req)

Gets the JReport Server UserSession object associated with the logged-in user for the web session. The UserSession object is stored in the servlet session related to the HttpServletRequest.

Parameters:

req - the HttpServletRequest.

Returns:

the UserSession object. Returns null when no user is logged-in.

setHttpExternalAuthorized

void setHttpExternalAuthorized(HttpExternalAuthorized externalAuthorized)

Sets the HttpExternalAuthorized class that will be used by checkLogin() to authenticate a user for the session.
This allows dynamically changing the HttpExternalAuthorized class from the one established in the command line that starts JReport Server.

Parameters:

externalAuthorized - the HttpExternalAuthorized.

See Also:

HttpExternalAuthorized.

getHttpExternalAuthorized

HttpExternalAuthorized getHttpExternalAuthorized()

Gets the HttpExternalAuthorized class that is registered to be used by checkLogin().

Returns:

the HttpExternalAuthorized.

See Also:

HttpExternalAuthorized.

removeExpiredUserSessions

void removeExpiredUserSessions(javax.servlet.http.HttpServletRequest req)

Removes the expired user sessions (exceeding the max inactive interval).

Parameters:

req - the HttpServletRequest.

loginMD5

UserSession loginMD5(java.lang.String realm,
                     java.lang.String userID,
                     java.lang.String digestResponse,
                     java.lang.String unquotedNonce,
                     java.lang.String digestURI,
                     java.lang.String httpMethod,
                     java.lang.Object extObj)
              throws TooManyUsersException

Logs in a user with the digest MD5 method.

Parameters:

realm - the realm.

userID - the user ID.

digestResponse - the digest response.

unquotedNonce - the unquoted nonce.

digestURI - the digest URI.

httpMethod - the HTTP method.

extObj - the external object attached to the user session.

Returns:

the user session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

See Also:

UserSession

loginMD5

UserSession loginMD5(java.lang.String realm,
                     java.lang.String userID,
                     java.lang.String digestResponse,
                     java.lang.String unquotedNonce,
                     java.lang.String digestURI,
                     java.lang.String httpMethod,
                     java.lang.Object extObj,
                     boolean isWait)
              throws TooManyUsersException

Logs in a user with the digest MD5 method.

Parameters:

realm - the realm.

userID - the user ID.

digestResponse - the digest response.

unquotedNonce - the unquoted nonce.

digestURI - the digest URI.

httpMethod - the HTTP method.

extObj - the external object attached to the user session.

isWait - whether wait.

Returns:

the user session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

See Also:

UserSession

checkLogin

boolean checkLogin(javax.servlet.http.HttpServletRequest req,
                   java.lang.String realm,
                   java.util.Properties query)
            throws TooManyUsersException,
                   TooManyTimesException,
                   java.io.IOException

Deprecated. This method has been deprecated since V8. You should use its overloaded method checkLogin(req, res, realm, query), if you want to provide a special extra channel feature for admin user.

Performs an authentication check for the current HTTP Request.

Returns true if an authenticated JReport Server user is logged-in to the session.

If a user is not logged-in, it attempts to log in a user based on the HttpExternalAuthorized login framework, and the current HTTP Request parameter and the query Properties parameter passed in to it.

First, it calls the HttpExternalAuthorized class method getExternalAuthorizedUser().
If this returns a valid JReport user id, it logs this user into the JReport session.
If this does not return a valid user id, it looks in the HTTP Request header for the Authorization field (following the current HTTP Authentication protocol settings, either Basic or Digest), and uses what it finds as the name/password credentials to validate as a known JReport user.
If the header has credentials and they validate, it logs this user into the JReport session.
If the HTTP Request header does not contain credentials that validate, it looks in the query Properties parameter for either the pair of attributes APIConst.TAG_AUTH_UID and APIConst.TAG_AUTH_PWD or the single attribute APIConst.TAG_AUTHORIZATION, and uses the attribute values or value to get the name/password credentials to validate.
If these exist and the values validate, it logs this user into the JReport session.

(Note that the HttpServletRequst query parameters are not looked at for these attributes. The caller should move these URL query parameters from the HttpServletRequst to the query Properties parameter before calling checkLogin.)

When a user is logged into the JReport session based on credentials that checkLogin validates during this call, a new UserSession is established within the servlet session so that subsequent calls to checkLogin can return true immediately based on a user being logged-in.

If checkLogin is able to log in a user during this call it returns true.
If checkLogin does not find a user already logged-in and can not log in a user following this process, it returns false.

Parameters:

req - the HttpServletRequest.

realm - the realm.

query - a Properties structure holding the URL parameter key/value pairs built from the HTTP query fields in the HttpServletRequest.

Returns:

true if a JReport Server user is currently logged-in or can be logged-in to this servlet session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

TooManyTimesException - if a TooManyTimesException occurs.

java.io.IOException - if an IOException occurs.

See Also:

UserSession, HttpUtil.checkLogin()

checkAdminLogin

boolean checkAdminLogin(javax.servlet.http.HttpServletRequest req,
                        java.lang.String realm,
                        java.util.Properties query)
                 throws TooManyUsersException,
                        TooManyTimesException,
                        java.io.IOException

Deprecated. This method has been deprecated since V8. You should use its overloaded method checkAdminLogin(req, res, realm, query), if you want to provide a special extra channel feature for admin user.

Performs an authentication check for the current HTTP Request looking for an admin user.

Returns true if an authenticated JReport Server admin user is logged-in to the session. If a user is logged-in, but the user is not an admin user, it returns false.

If a user is not logged-in, it attempts to log in an admin user based on the HttpExternalAuthorized login framework, and the current HTTP Request parameter and the query Properties parameter passed in to it.

First, it calls the HttpExternalAuthorized class method getExternalAuthorizedUser().
If this returns a valid JReport admin user id, it logs this admin user into the JReport session.
If this does not return a valid admin user id, it looks in the HTTP Request header for the Authorization field (following the current HTTP Authentication protocol settings, either Basic or Digest), and uses what it finds as the name/password credentials to validate as a known JReport admin user.
If the header has credentials and they validate, it logs this admin user into the JReport session.
If the HTTP Request header does not contain credentials that validate, it looks in the query Properties parameter for either the pair of attributes APIConst.TAG_AUTH_UID and APIConst.TAG_AUTH_PWD or the single attribute APIConst.TAG_AUTHORIZATION, and uses the attribute values or value to get the name/password credentials to validate.
If these exist and the values validate an admin user, it logs this admin user into the JReport session.

(Note that the HttpServletRequst query parameters are not looked at for these attributes. The caller should move these URL query parameters from the HttpServletRequst to the query Properties parameter before calling checkAdminLogin.)

When a admin user is logged into the JReport session based on credentials that checkLogin validates during this call, a new UserSession is established within the servlet session so that subsequent calls to checkAdminLogin can return true immediately based on a user being logged-in.

If checkAdminLogin is able to log in an admin user during this call it returns true.
If checkAdminLogin does not find an admin user already logged-in and can not log in an admin user following this process, it returns false.

Parameters:

req - the HttpServletRequest.

realm - the realm.

query - a Properties structure holding the URL parameter key/value pairs built from the HTTP query fields in the HttpServletRequest.

Returns:

true if a JReport Server admin user is currently logged-in or can be logged-in to this servlet session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

TooManyTimesException - if a TooManyTimesException occurs.

java.io.IOException - if an IOException occurs.

checkLogin

boolean checkLogin(javax.servlet.http.HttpServletRequest req,
                   javax.servlet.http.HttpServletResponse res,
                   java.lang.String realm,
                   java.util.Properties query)
            throws TooManyUsersException,
                   TooManyTimesException,
                   java.io.IOException

Performs an authentication check for the current HTTP Request.

Returns true if an authenticated JReport Server user is logged-in to the session.

If a user is not logged-in, it attempts to log in a user based on the HttpExternalAuthorized login framework, and the current HTTP Request parameter and the query Properties parameter passed in to it.

First, it calls the HttpExternalAuthorized class method getExternalAuthorizedUser().
If this returns a valid JReport user id, it logs this user into the JReport session.
If this does not return a valid user id, it looks in the HTTP Request header for the Authorization field (following the current HTTP Authentication protocol settings, either Basic or Digest), and uses what it finds as the name/password credentials to validate as a known JReport user.
If the header has credentials and they validate, it logs this user into the JReport session.
If the HTTP Request header does not contain credentials that validate, it looks in the query Properties parameter for either the pair of attributes APIConst.TAG_AUTH_UID and APIConst.TAG_AUTH_PWD or the single attribute APIConst.TAG_AUTHORIZATION, and uses the attribute values or value to get the name/password credentials to validate.
If these exist and the values validate, it logs this user into the JReport session.

(Note that the HttpServletRequst query parameters are not looked at for these attributes. The caller should move these URL query parameters from the HttpServletRequst to the query Properties parameter before calling checkLogin.)

When a user is logged into the JReport session based on credentials that checkLogin validates during this call, a new UserSession is established within the servlet session so that subsequent calls to checkLogin can return true immediately based on a user being logged-in.

If checkLogin is able to log in a user during this call it returns true.
If checkLogin does not find a user already logged-in and can not log in a user following this process, it returns false.

Parameters:

req - the HttpServletRequest.

res - the HttpServletResponse.

realm - the realm.

query - a Properties structure holding the URL parameter key/value pairs built from the HTTP query fields in the HttpServletRequest.

Returns:

true if a JReport Server user is currently logged-in or can be logged-in to this servlet session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

TooManyTimesException - if a TooManyTimesException occurs.

java.io.IOException - if an IOException occurs.

See Also:

HttpExternalAuthorized, HttpUtil.checkLogin(), UserSession

checkAdminLogin

boolean checkAdminLogin(javax.servlet.http.HttpServletRequest req,
                        javax.servlet.http.HttpServletResponse res,
                        java.lang.String realm,
                        java.util.Properties query)
                 throws TooManyUsersException,
                        TooManyTimesException,
                        java.io.IOException

Performs an authentication check for the current HTTP Request looking for an admin user.

Returns true if an authenticated JReport Server admin user is logged-in to the session. If a user is logged-in, but the user is not an admin user, it returns false.

If a user is not logged-in, it attempts to log in an admin user based on the HttpExternalAuthorized login framework, and the current HTTP Request parameter and the query Properties parameter passed in to it.

First, it calls the HttpExternalAuthorized class method getExternalAuthorizedUser().
If this returns a valid JReport admin user id, it logs this admin user into the JReport session.
If this does not return a valid admin user id, it looks in the HTTP Request header for the Authorization field (following the current HTTP Authentication protocol settings, either Basic or Digest), and uses what it finds as the name/password credentials to validate as a known JReport admin user.
If the header has credentials and they validate, it logs this admin user into the JReport session.
If the HTTP Request header does not contain credentials that validate, it looks in the query Properties parameter for either the pair of attributes APIConst.TAG_AUTH_UID and APIConst.TAG_AUTH_PWD or the single attribute APIConst.TAG_AUTHORIZATION, and uses the attribute values or value to get the name/password credentials to validate.
If these exist and the values validate an admin user, it logs this admin user into the JReport session.

(Note that the HttpServletRequst query parameters are not looked at for these attributes. The caller should move these URL query parameters from the HttpServletRequst to the query Properties parameter before calling checkAdminLogin.)

When a admin user is logged into the JReport session based on credentials that checkLogin validates during this call, a new UserSession is established within the servlet session so that subsequent calls to checkAdminLogin can return true immediately based on a user being logged-in.

If checkAdminLogin is able to log in an admin user during this call it returns true.
If checkAdminLogin does not find an admin user already logged-in and can not log in an admin user following this process, it returns false.

Parameters:

req - the HttpServletRequest.

res - the HttpServletResponse.

realm - the realm.

query - a Properties structure holding the URL parameter key/value pairs built from the HTTP query fields in the HttpServletRequest.

Returns:

true if a JReport Server admin user is currently logged-in or can be logged-in to this servlet session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

TooManyTimesException - if a TooManyTimesException occurs.

java.io.IOException - if an IOException occurs.

checkLoginEx

boolean checkLoginEx(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse res,
                     java.lang.String realm,
                     java.util.Properties query)
              throws TooManyUsersException,
                     TooManyTimesException,
                     java.io.IOException,
                     InvalidUserException

Performs an authentication check for the current HTTP Request.

Returns true if an authenticated JReport Server user is logged-in to the session.

If a user is not logged-in, it attempts to log in a user based on the HttpExternalAuthorized login framework, and the current HTTP Request parameter and the query Properties parameter passed in to it.

First, it calls the HttpExternalAuthorized class method getExternalAuthorizedUser().
If this returns a valid JReport user id, it logs this user into the JReport session.
If this does not return a valid user id, it looks in the HTTP Request header for the Authorization field (following the current HTTP Authentication protocol settings, either Basic or Digest), and uses what it finds as the name/password credentials to validate as a known JReport user.
If the header has credentials and they validate, it logs this user into the JReport session.
If the HTTP Request header does not contain credentials that validate, it looks in the query Properties parameter for either the pair of attributes APIConst.TAG_AUTH_UID and APIConst.TAG_AUTH_PWD or the single attribute APIConst.TAG_AUTHORIZATION, and uses the attribute values or value to get the name/password credentials to validate.
If these exist and the values validate, it logs this user into the JReport session.

(Note that the HttpServletRequst query parameters are not looked at for these attributes. The caller should move these URL query parameters from the HttpServletRequst to the query Properties parameter before calling checkLogin.)

When a user is logged into the JReport session based on credentials that checkLogin validates during this call, a new UserSession is established within the servlet session so that subsequent calls to checkLogin can return true immediately based on a user being logged-in.

If checkLogin is able to log in a user during this call it returns true.
If checkLogin does not find a user already logged-in and can not log in a user following this process, it returns false.

Parameters:

req - the HttpServletRequest.

res - the HttpServletResponse.

realm - the realm.

query - a Properties structure holding the URL parameter key/value pairs built from the HTTP query fields in the HttpServletRequest.

Returns:

true if a JReport Server user is currently logged-in or can be logged-in to this servlet session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

TooManyTimesException - if a TooManyTimesException occurs.

java.io.IOException - if an IOException occurs.

InvalidUserException - if the user is not valid.

See Also:

HttpExternalAuthorized, HttpUtil.checkLogin(), UserSession

checkAdminLoginEx

boolean checkAdminLoginEx(javax.servlet.http.HttpServletRequest req,
                          javax.servlet.http.HttpServletResponse res,
                          java.lang.String realm,
                          java.util.Properties query)
                   throws TooManyUsersException,
                          TooManyTimesException,
                          java.io.IOException,
                          InvalidUserException

Performs an authentication check for the current HTTP Request looking for an admin user.

Returns true if an authenticated JReport Server admin user is logged-in to the session. If a user is logged-in, but the user is not an admin user, it returns false.

If a user is not logged-in, it attempts to log in an admin user based on the HttpExternalAuthorized login framework, and the current HTTP Request parameter and the query Properties parameter passed in to it.

First, it calls the HttpExternalAuthorized class method getExternalAuthorizedUser().
If this returns a valid JReport admin user id, it logs this admin user into the JReport session.
If this does not return a valid admin user id, it looks in the HTTP Request header for the Authorization field (following the current HTTP Authentication protocol settings, either Basic or Digest), and uses what it finds as the name/password credentials to validate as a known JReport admin user.
If the header has credentials and they validate, it logs this admin user into the JReport session.
If the HTTP Request header does not contain credentials that validate, it looks in the query Properties parameter for either the pair of attributes APIConst.TAG_AUTH_UID and APIConst.TAG_AUTH_PWD or the single attribute APIConst.TAG_AUTHORIZATION, and uses the attribute values or value to get the name/password credentials to validate.
If these exist and the values validate an admin user, it logs this admin user into the JReport session.

(Note that the HttpServletRequst query parameters are not looked at for these attributes. The caller should move these URL query parameters from the HttpServletRequst to the query Properties parameter before calling checkAdminLogin.)

When a admin user is logged into the JReport session based on credentials that checkLogin validates during this call, a new UserSession is established within the servlet session so that subsequent calls to checkAdminLogin can return true immediately based on a user being logged-in.

If checkAdminLogin is able to log in an admin user during this call it returns true.
If checkAdminLogin does not find an admin user already logged-in and can not log in an admin user following this process, it returns false.

Parameters:

req - the HttpServletRequest.

res - the HttpServletResponse.

realm - the realm.

query - a Properties structure holding the URL parameter key/value pairs built from the HTTP query fields in the HttpServletRequest.

Returns:

true if a JReport Server admin user is currently logged-in or can be logged-in to this servlet session.

Throws:

TooManyUsersException - if a TooManyUsersException occurs.

TooManyTimesException - if a TooManyTimesException occurs.

java.io.IOException - if an IOException occurs.

InvalidUserException - if the user is not valid.

sendUnauthorizedResponse

void sendUnauthorizedResponse(javax.servlet.http.HttpServletRequest req,
                              javax.servlet.http.HttpServletResponse res,
                              java.lang.String authScheme,
                              java.lang.String realm)
                       throws java.io.IOException

Sends an HTTP unauthorized response (HTTP 401) to the client.

Parameters:

req - the HttpServletRequest.

res - the HttpServletResponse.

authScheme - the authentication scheme. The available value is "Basic" or "Digest".

realm - the realm.

Throws:

java.io.IOException - if an IOException occurs.

logout

void logout(javax.servlet.http.HttpServletRequest req)

Logs out the JReport Server user who is currently logged into the web session. The current user is the one identified in the UserSession object stored in the servlet session related to the HttpServletRequest. On return from logout(), no user is logged-in.

Parameters:

req - the HttpServletRequest.

isExtraChannel

boolean isExtraChannel(javax.servlet.http.HttpServletRequest req)

Checks whether the current HTTP Request is associated with a logged-in user session that was allowed to login under the special extra channel situation.

If the current logged-in user was allowed to login when the full set of licensed users was already logged-in, then the session is using the special extra channel. Based on the return value of this method, you can control and manage access rights for this special-channel user.

For example, you can deny requests to run reports or submit schedules during this session for this special-channel user.

Parameters:

req - the HttpServletRequest.

Returns:

true if the current logged-in session is associated with the special extra channel, or else returns false.