ePages 6.11.0 - DE_EPAGES/Presentation/Servlet/Permission.pm

Package DE_EPAGES::Presentation::Servlet::Permission

This servlet is the main dispatcher for all permission-based URL events. The application server function DE_EPAGES::WebInterface::API::ApplicationServer::run Chooses the actually used servlet package based on the configuration file $ENV{EPAGES_CONFIG}/Servlet.conf. Then it executes the methods new, init and handle on the servlet to process an incoming request.

Base
DE_EPAGES::WebInterface::Servlet::BaseServlet
Example
# create a new servlet object
my $Servlet = $Package->new;
# initialize the servlet with parameters from the Servlet.conf section
$Servlet->init( \%Parameters ) if $Handler->can( 'init' );
# create the respose from the request
$Servlet->handle( $Request, $Response );

Functions

action
addBaseLineURL
baseLineContentLocation
checkDomain
cookies
cookiesAtPath
cookiesEnabled
createAnonymousUser
createSecurityToken
currencyID
defaults
doAction
doActions
doChangeActions
doViewAction
form
handleEncodingFormError
handleError
handleInvalidForm
handleMonitorNotFound
handleObjectNotFound
handlePermissionDenied
handleRequest
handleSiteIsClosed
handleStoreNotFound
handleWrongUrlParameter
hasPermission
historyUri
init
intSessionID
isEditorMode
isEditorNavElements
languageID
locale
logUserFault
logout
monitor
monitorThread
new
object
params
processContent
processErrorContent
processMonitorContent
redirect
registerSession
saveHistory
setCurrencyID
setLocale
site
testPermission
user
vars
verifySecurityToken
viewError
viewInvalidURLError
viewObject
writeContentOutput

action

Returns the current action, else undef.

Syntax
$Action = $Servlet->action;
Return
$Action (object)
current action

addBaseLineURL

adds base to response if necessary. if found head tag then the html tag base will be appended to the head tag, otherwise the obsolate Content-Base http header tag is added.

Syntax
$Servlet->addBaseLineURL;

baseLineContentLocation

Builds the base url. This url includes the path info. The path info is used to save cookies at the url if cookies are not enabled or never send before.

Syntax
my $BaseLineContentLocation = $Servlet->baseLineContentLocation($UseSSL, $Object);
Input
$UseSSL (object)
url is for ssl (optional)
$Object (object)
object to switch context (https/http) (optional)
Return
$BaseLineContentLocation (string)
url (eg 'http://localhost/epages/Store.storefront/;SessionID=429D7D210002A446273DAC14142B0603' )

checkDomain

Checks if the object is allowed to be requested via the $DomainName. The root object is always accessible. IP-Addresses and domain names not including a dot are always allowed. In addition, each object can be requested via the domain configured for it's site object or the domains configured as webserver host or webserver SSL host in the technical administration.

Syntax
$IsValid = $Servlet->checkDomain( $Object, $DomainName );
if (!checkDomain($Object, 'www.epages.de')) { ... }
Input
$Object (boolean)
object
$DomainName (string)
server name or ip address from the HTTP "Host" header
Return
$IsValid (boolean)
true if the domain name is valid for the object

cookies

Without parameter returns the function cookies which was served by the request. On first run on servlet the form will be encoded.
With one parameter (name of cookie) the value of this cookie will be returned.
With two parameter (name and value of cookie) the value of this cookie will be set (includes send to client and set in vars).

Syntax
$Cookies = $Servlet->cookies;
$Cookie= $Servlet->cookies($Name);
$Servlet->cookies($Name, $Value);
$Servlet->cookies($Name, $Value, $hOptions);
Input
$Name (string)
name of cookie (optional)
$Value (string)
value of cookie (optional)
$hOptions (ref.hash)
cookie options (optional), see
DE_EPAGES::WebInterface::API::Cookie::SetCookie
Return
$Cookies (ref.hash)
cookies key value pairs (optional)
$Cookie (string)
value of given cookie name (optional)

cookiesAtPath

Returns true if the session state is appended to the PATH_INFO part of the URL, for example if the browser does not accept cookies.

Syntax
$CookiesAtPath = $Servlet->cookiesAtPath;
Return
$CookiesAtPath (boolean)
true if session state is added to the URL

cookiesEnabled

Returns true if the client browser accepts cookies. Checks if the HTTP Header "Cookie:" exists in the request.

Syntax
$Enabled = $Servlet->cookiesEnabled;
Return
$Enabled (boolean)
true if the browser accepts cookies

createAnonymousUser

Returns the new anonymous user. The user will be registered at $Site.

Syntax
$User = $Servlet->createAnonymousUser($Site);
Input
$Site (object)
Site (shop/system)
Return
$User (object)
User

createSecurityToken

Builds the security token or locale for url. The security Token starts always with 'sec'

Syntax
my $TokenOrLocale = $Servlet->createSecurityToken;
Return
$TokenOrLocale (string)
url part (eg 'en_US' or 'secjyQOO3ejO.w')

currencyID

Returns the currency id of the current request. The id is determined from the request parameters, user preferences, cookies or site preferences. If no currency was found, the default is used.

Syntax
$CurrencyID = $Servlet->currencyID;
$CurrencyID = $Servlet->currencyID($Reset);
Input
$Reset (boolean)
reset local saved values (eg: login of user)
Return
$CurrencyID (char(3))
currency id (e.g. 'EUR', default='USD')

defaults

Without parameter returns defaults of Locale,Language,OutputEncoding.
With one parameter (name of defaults variable) the value of this defaults variable will be returned.

Syntax
$Defaults = $Servlet->defaults;
$Value= $Servlet->defaults($Name);
Input
$Name (string)
name of defaults variable (optional)
Return
$Defaults (ref.hash)
defaults key value pairs (optional)
$Value (string)
value of given defaults variable name (optional)

doAction

Executes an event handler if the current user has sufficient permissions.

Syntax
$Result = $self->doAction( $Action )
Example
$Result = $self->doAction( 'DeleteCompany' );
Input
$Action (string)
Name of an URLAction
Return
$Result (?)
whatever the event handler returns

doActions

Executes all change actions and then executes the view action. Processing is terminated immediately at the first error. Calls handleError if an error occurs while processing an action.

Syntax
$Servlet->doActions;

doChangeActions

Executes all ChangeActions in the order of their appearance in the form or URL. Access permissions are checked before running the event handler.

Syntax
$self->doChangeActions;

doViewAction

Executes a ViewAction and fills the HTTP response using the template and TLE variables provided by the event handler function. Access permissions are checked before running the event handler.

Syntax
$Servlet->doViewAction;

form

Returns the form which was served by the request. On first run on servlet the form will be encoded.

Syntax
$Form = $Servlet->form;
Example
my $Form = $Servlet->form;
Return
$Form (object)
DE_EPAGES::Presentation::API::Form object

handleEncodingFormError

Handles the error "false encoding in url". This function sets the HTTP status 400 - "Bad Request" and displays an error message and logs a warning message containing QUERY_STRING and HTTP_REFERER.

Syntax
$Servlet->handleEncodingFormError( $Error );
Input
$Error (object)
error object

handleError

Handles an error. This function logs the error and then displays it using the viewError method.

Syntax
$Servlet->handleError( $Error );
Input
$Error (object)
error object

handleInvalidForm

calls doViewAction for the given error.

Syntax
$self->handleInvalidForm($Error, $OnChangeAction, $ErrorAction, $ErrorObjectID);
Input
$Error (object)
error object
$OnChangeAction (boolean)
call on change or view action (used for some tests)
$ErrorAction (object)
error action (optional)
$ErrorObjectID (integer)
error object identifier (optional)

handleMonitorNotFound

Handles the error "FILE_NOT_FOUND" for not found monitor files. This function sets the HTTP status 404 - "Object not found" and displays an error message and logs a warning message containg QUERY_STRING and HTTP_REFERER.

Syntax
$Servlet->handleMonitorNotFound( $Error );
Input
$Error (object)
error object

handleObjectNotFound

Handles the error "Object not found" or "Path not found". This function sets the HTTP status 404 - "Object not found" and displays an error message and logs a warning message containg QUERY_STRING and HTTP_REFERER.

Syntax
$Servlet->handleObjectNotFound( $Error );
Input
$Error (object)
error object

handlePermissionDenied

Dispays the login form as a result of an unauthorized view action. Triggers the action ViewSimpleLoginForm and sets the followg TLE variables:

Syntax
$Servlet->handlePermissionDenied( $Error );
Input
$Error (object)
error object

handleRequest

Handles the request and produces a response. Connect to the database and executes ChangeActions and the ViewAction.

Syntax
$Servlet->handleRequest;

handleSiteIsClosed

Handles the error "Site is closed". This function sets the HTTP status 503 - "This Web site has been temporarily closed.".

Syntax
$Servlet->handleSiteIsClosed( $Error );
Input
$Error (object)
error object

handleStoreNotFound

This function sets the HTTP status 404 - "Not Found" and displays an error message and logs a warning message containing QUERY_STRING and HTTP_REFERER.

Syntax
$Servlet->handleStoreNotFound( $Error );
Input
$Error (object)
error object

handleWrongUrlParameter

Handles the error "url parameter has wrong value ". This function sets the HTTP status 400 - "Bad Request" and displays an error message and logs a warning message containing QUERY_STRING and HTTP_REFERER.

Syntax
$Servlet->handleWrongUrlParameter( $Error );
Input
$Error (object)
error object

hasPermission

Returns true if the current user has permission to execute an action. Loggs off the current user if the site is standalone and the user does not belong to this site.

Syntax
$HasPermission = $Servlet->hasPermission( $Object, $ActionName);
$HasPermission = $Servlet->hasPermission( $Object, $Action);
Example
unless( $Servlet->hasPermission( $Object, 'Delete' ) ) {
    print "Access denied";
}
Input
$Object (object)
object
$Action (object)
action object
$ActionName (string)
name of action
Return
$HasPermission (boolean)
true if permission is granted

historyUri

returns uri for history.

Syntax
$Servlet->historyUri;

init

Copies the parameters ViewAction, Locale and IsEditorModeEnabled from the Servlet.conf file to vars.

Syntax
$Servlet->init( $hParams );
Input
$hParams (ref.hash.string)
hash with servlet parameter

intSessionID

Returns the internal session id of the current request. A form parameter with the name "SessionID" takes precedence over a cookie with the name "SessionID" (external sessionid).

Syntax
$SessionID = $Servlet->intSessionID;
Return
$SessionID (int)
internal session id or undef if no session id was found

isEditorMode

isbackoffice request (from form data)

Syntax
$IsEditorMode = $Servlet->isEditorMode;
Return
$IsEditorMode (boolean)
template should be processed with editor

isEditorNavElements

Returns whether the "IsEditorNavElements" parameter is set, indicating a preview frame with the SF in quick design / adv. design mode.

Syntax
$isDesignEditor = $Servlet->isEditorNavElements;
Return
(boolean)
1 if in design mode, otherwise 0

languageID

Returns the language id of the current request. The id is determined from language that corresponds to the current locale. See locale.

Syntax
$LanguageID = $Servlet->languageID;
Return
$LanguageID (int)
integer language id (default is english)

locale

Returns the locale id of the current request. The id is determined from the request parameters, Cookie or object attribute. If no locales was found ,the default is used.

Syntax
$LocaleID = $Servlet->locale;
$LocaleID = $Servlet->locale($Reset);
Input
$Reset (boolean)
reset local saved values (eg: login of user)
Return
$LocaleID (string)
locale id (e.g. 'de_DE', default='en_US')

logUserFault

Logs a short message without stack trace using the log level "WARN" and log category 'USERFAULT::'.$Error->code

Syntax
$Servlet->logUserFault( $Error );

logout

Invalidates the current session of the logged-on user. Deletes the session from the database and clears the cookies SessionID and UserGUID.

Syntax
$Servlet->logout;

monitor

Returns the monitor object.

Syntax
$Monitor = $Servlet->monitor;
Return
$Monitor (object)
instance of DE_EPAGES::WebInterface::API::Object::MonitorShared

monitorThread

Returns the monitor thread of the servlet.

Syntax
$MonitorThread = $Servlet->monitorThread;
Return
$MonitorThread (object)
instance of DE_EPAGES::Core::API::Object::MonitorThread

new

Create a new servlet, set defaults on servlet like Locale,Language, OutputEncodinfg.

Syntax
$Servlet = new DE_EPAGES::Presentation::Servlet::Permission;
Example
my $PermissionServlet = new DE_EPAGES::Presentation::Servlet::Permission;
Return
$Servlet (object)
blessed object

object

Returns the object on which the current action operates.

Syntax
$Object = $Servlet->object;
Return
$Object (object)
object of the current request

params

This function gives an central access to all parameter of the request. No matter it comes as cookie, parameter, form field or set in set meantime with vars. Without parameter returns the function all parameter which was served by the request and set via the request invars.
With one parameter (name of variable) the value will be returned.
With two parameter (name and value of variable) the value will be set (with function vars).

Syntax
$Params = $Servlet->params;
$Value = $Servlet->params($Name);
$Servlet->params($Name, $Value);
Input
$Name (string)
name of variable (optional)
$Value (string)
value of variable (optional)
Return
$Params (ref.hash)
params key value pairs (optional)
$Value (string)
value of given variable name (optional)

processContent

process template and var hash to response string

Syntax
$Content = $Servlet->processContent;
Return
$Content (string)
processed template

processErrorContent

Builds an error message using the SimpleError template in English.

Syntax
$Servlet->processErrorContent( $Error );
Input
$Error (object)
error object

processMonitorContent

Creates the content of the default monitor page.

Syntax
$Servlet->processMonitorContent($FileName, $hVars);
Input
$FileName (string)
monitor template file name
(optional, default: $self->params('MonitorFileName')
$hVars (ref.hash.string)
additional TLE variables (optional)

redirect

Redirects the browser to another URL.

Syntax
$Servlet->redirect( $Location );
$Servlet->redirect( $Location, $StatusCode );
Input
$Location (string)
target URL
$StatusCode (int)
(optional, default: 301) HTTP status code

registerSession

creates a new session id and save this as cookie. Applies the locale and currency preferences of the user ($User).

Syntax
$IntSessionID = $Servlet->registerSession($User, $PerCookie);
Input
$User (object)
user (optional)
$PerCookie (bit)
user identified by cookie (optional)
Return
$IntSessionID (string)
processed template

saveHistory

Adds the URI and page title of the current request to the session history in the database. The URI is returned by historyUri. The page title is composed from the action name and $self->params('Title') or object name.

Syntax
$Servlet->saveHistory;

setCurrencyID

Sets the currency for the current user. Creates a new anonymous user if there is currently no user.

Syntax
$Servlet->setCurrencyID($CurrencyID);
Example
$Servlet->setCurrencyID('USD');
Input
$CurrencyID (string)
locale id (e.g. 'USD')

setLocale

Sets the locale for the current request by modifying the URL of the next pages. If the session is associated with a user and $SetUser is true, then the user default locale is also changed.

Syntax
$Servlet->setLocale($LocaleID);
$Servlet->setLocale($LocaleID, $SetUser);
Example
$Servlet->setLocale($LocaleID);
$Servlet->setLocale($LocaleID, 0);
Input
$LocaleID (string)
locale id (e.g. 'de_DE')
$SetUser (boolean)
should the servlet modify the user's locale settings in the
session, optional, default is 1

site

Gets the site object of the current request from the X-ePages-Site header.

Syntax
$Site = $Servlet->site;
Return
$Site (object)
site of the current request

testPermission

Verifies if the current user has permission to execute a selected Event. Throws an error if permission is denied.

Syntax
$Servlet->testPermission( $Object, $Action);
$Servlet->testPermission( $Object, $ActionName);
Example
eval { $Servlet->testPermission( $Object, 'Delete' ); }
if( ExistsError() && GetError()->code eq 'PermissionDenied' ) {
    print "Access denied";
}
Input
$Object (object)
object
$Action (object)
action object
$ActionName (string)
name of action

user

Returns the user from the current session. The user is determined from the SessionID parameter.

Syntax
$user = $Servlet->user;
Return
$user (object)
user or undef if no session id was found

vars

Without parameter returns all set variables.
With one parameter (name of variable) the value of this variable will be returned.
With two parameter (name and value of variable) the value of this variable will be set.

Syntax
$hVars = $Servlet->vars;
$Value= $Servlet->vars($Name);
$Servlet->vars($Name, $Value);
Example
$Servlet->vars('OutputEncoding', 'ISO-8859-1');
Input
$Name (string)
name of variable (optional)
$Value (string)
value of variable (optional)
Return
$hVars (ref.hash)
set TLE variables as key value pairs
$Value (string)
value of given variable name

verifySecurityToken

Reads security token or locale from url. No error if token correct or no user logged in.

Syntax
$Servlet->verifySecurityToken;

viewError

Displayse an error page, which is processed by processErrorContent.

Syntax
$Servlet->viewError( $Error );
Input
$Error (object)
error object

viewInvalidURLError

Displayse an invalid url error, which is processed by processErrorContent.

Syntax
$Servlet->viewInvalidURLError( $Error );
Input
$Error (object)
error object

viewObject

Returns the Object for the ViewAction.

Syntax
my $Object = $Servlet->viewObject;

writeContentOutput

Fills the HTTP response with the given content in the correct encoding. Hint: you can set the output encoding and content-type via the servlet parameters, eg: $Servlet->vars('OutputEncoding', 'utf-8'); $Servlet->vars('ContentType', 'text/x-json');

Syntax
$Servlet->writeContentOutput($Content);
Input
$Content (string)
your content