ePages 6.17.43 - 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::Presentation::Servlet::BasePermission
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
catchFormError
checkDomain
connectionCfgValue
cookies
cookiesAtPath
cookiesEnabled
createAnonymousUser
createSecurityToken
csrfPredator
currencyID
defaults
doAction
doActions
doChangeActions
doViewAction
forcePOSTForNonTestShops
form
handleEncodingFormError
handleError
handleInvalidForm
handleMonitorNotFound
handleObjectNotFound
handlePermissionDenied
handleRequest
handleSiteIsClosed
handleWrongUrlParameter
hasPermission
historyUri
init
intSessionID
isEditorMode
isEditorNavElements
isPOSTRequest
isSecureConnection
languageID
locale
logUserFault
logout
mobileURL
monitor
new
object
params
processContent
processErrorContent
processMonitorContent
redirect
redirectToSecureConnection
registerSession
setCurrencyID
setLocale
site
testPermission
testPostRequest
testSecureConnection
testSessionIntegrity
user
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' )

catchFormError

Catch triggering of form errors. This allows you to add necessary TLE variables for displaying the user input form without having to specify a separate ErrorAction. For use within ViewAction without any ChangeActions only!

Syntax
$self->catchFormError( $cSub );
Example
 $Servlet->catchFormError( sub {
     $Servlet->form->executeFormError( ... );
 });
Input
$cSub (ref.code)
code to run

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

connectionCfgValue

Get information about current database connection by using DE_EPAGES::Database::API::Config::DatabaseConnectionData

Syntax
$Value = $self->connectionCfgValue($Key);
Input
$Key (string)
name of key value pair
Return
$Value (string/integer)
return valu from config

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')

csrfPredator

Returns a CSRFPredator object with request specific secrets.

Syntax
$Predator = $Servlet->csrfPredator();
Return
$Predator (object)
instance of DE_EPAGES::Permission::API::Object::CSRFPredator

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 )
$Result = $self->doAction( $ActionName )
Example
$Result = $self->doAction( 'DeleteCompany' );
Input
$ActionName (string)
Name of an URLAction
$Action (object)
action object
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;

forcePOSTForNonTestShops

Checks if request is a POST request. If this check fails a form error is executed. Internal test shops are not checked.

Syntax
$Servlet->forcePOSTForNonTestShops();

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

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;
Return
$HistoryURI (string)
URL

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

isPOSTRequest

Return true if current request was send with method POST.

Syntax
$Servlet->isPOSTRequest();
Return
$IsPost (boolean)
Is post request ?

isSecureConnection

Determines if the request was sent on a secure port, given the store got a SSL certificate. Returns always 1 if there's no server SSL certificate at all.

Syntax
$Servlet->isSecureConnection();
Example
unless ($Servlet->isSecureConnection()) {
    # error handling, redirect, logging, ...
}
Return
$IsSecure (boolean)
secure connection indicator

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 );
Input
$Error (DE_EPAGES::Core::API::Error)
error object

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;

mobileURL

Converts a given storefront URL to the corresponding URL for mobile devices by replacing ".sf" by ".mobile". Protocol, host name and query parameters remain unchanged.

Syntax
my $MobileURL = $Servlet->mobileURL( $StorefronURL );
Input
$StorefronURL (string)
storefront URL
Return
$MobileURL (string)
mobile URL

monitor

Returns the monitor object.

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

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
$Content = $Servlet->processErrorContent( $Error );
Input
$Error (object)
error object
Return
$Content (string)
error message

processMonitorContent

Returns the functions to generate the content of the monitor page and the finish page. Returns undef if no monitor page shall be used.

Syntax
$MonitorContentSub = $Servlet->processMonitorContent
Return
$hMonitorContent (ref.hash)
see <fuction DE_EPAGES::Core::API::Object::MonitorShared::new>
  • MonitorContentSub - sub to create the content of the monitor page - string
  • FinishedContentSub - sub to create the content of the finish page - string

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

redirectToSecureConnection

Abort the current action and reloads the current GET request on a secure connection using the given secure domain URL if isSecureConnection returns false. For use in sensitive ViewActions which require a secure connection.

Syntax
$Servlet->redirectToSecureConnection($DomainURL);
Example
$Servlet->redirectToSecureConnection(
    $Servlet->object->getSite->get('WebServerScriptUrlSSL')
);
Input
$DomainURL (string)
secure URL for redirect

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

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

testPostRequest

Abort the current action and displays a POST_REQUIRED_FOR_REQUEST error page with status code 403 if isPOSTRequest returns false. For use in sensitive ChangeActions which require more security.

Syntax
$Servlet->testPostRequest();

testSecureConnection

Abort the current action and displays a SSL_REQUIRED_FOR_LOGIN error page with status code 403 if isSecureConnection returns false. For use in sensitive ChangeActions which require a secure connection.

Syntax
$Servlet->testSecureConnection();

testSessionIntegrity

Check if current request matches the 'UserAgent' and 'RemoteIP' stored in the current session. The later is only checked for administrative requests (MBO/PBO/Diagnostics). May throw SESSION_WRONG_UA, SESSION_WRONG_ADDR

Syntax
$Servlet->testSessionIntegrity($SessionID);
Input
$SessionID (integer)
current session id

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

verifySecurityToken

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

Syntax
$Servlet->verifySecurityToken;

viewError

Displays 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;
Return
$Object (DE_EPAGES::Object::API::Object::Object)
currently active object

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

Package My::FakeMonitor