DESIGN DESCRIPTION

Mentata LDAPHttp Framework

4. Detailed design

This section details the rewrite of the original LDAPHttp software for better security, compatibility, extensibility, and maintainability. This newer version makes use of properties files, Java Beans, and JavaServer Pages. The design also separates servlets from the core libraries to enable easier extension to other types of services or clients.

L3D

The package com.mentata.l3d provides extensible capability around three central abstract classes: contexts, objects, and attributes. It represents the portion of the LDAPHttp framework that does not involve web content or servlets. Sets of subclasses stored together in designated locations of the class hierarchy with properties files define local use of the paradigm.

L3DContext

Instances of this class are constructed by parsing a formatted text file named ‘context.properties’ located in a package named for the context under com.mentata.l3d in the Java class hierarchy. It is defined by properties for identifying a directory server, configuring pool of connections to be used with the server, setting encryption standards for directory communication, characterizing authentication, associating a locale, and specifying an associated Java package of objects. Almost all options have defaults that work for simple situations, minimizing the need for their definition. An instance is immutable and offers limited access after its creation. A context is used for getting directory connections or instances of objects that are in an associated Java package.

L3DObject

This abstract class can be extended in context packages to correspond with one or more object classes from the target directory's schema, a specific location in the directory tree, filters, and other identifying characteristics. Each instance defines a set of L3DAttributes, often yet not always corresponding to those permitted in the directory schema. An instance may also define basic traits such as a friendly label, default sort behavior, a search limit, or use of incremental identifiers. An L3DObject initially represents a template container for an entry with no attribute values. There are no methods to manipulate this structure from without, but attribute values can be defined either manually or by populating the template with an identified directory entry. The attributes themselves are then available as L3DAttributes, providing access to type-specific functionality. An L3DObject instance can be bound with a directory connection for use in internal operations throughout its life. Given an authoritative connection, a populated L3DObject can be used to create, delete, or modify a corresponding entry in the database. Supporting methods also enable searching for entries, instantiating other objects in the same context, labelling attributes either explicitly or through external properties files, setting a locale, getting localized date/time stamps, and managing lists of attributes for various purposes.

L3DAttribute

This class can be extended by various attribute types that all implement the same basic functionality. Attributes are created and configured from within an object and can correspond with a specific attribute for the associated object class in the directory schema. A given L3DAttribute is configured to be optional or required and to have a single value or multiple values, not necessarily in accordance with the schema definition. Attributes can be populated with values from a corresponding entry in the directory database or manipulated with methods to initialize, set, add, or remove values. The class includes supporting methods for comparing values, sorting values, setting a limit on the number of values, setting a length limit for each value, accessing the containing object, accessing a bound connection for the containing object, and getting directory connections directly from the containing context. For its original implementation, this class stores and compares its values as simple, case-insensitive Unicode strings.

L3DDnAttribute

This subclass of L3DAttribute stores and compares its values as LDAP distinguished names. Upon construction, an instance can be associated with another object in the same context to serve as the target for entries pointed to by its values. L3DDnAttributes can be initialized with identifiers instead of literal distinguished names.

L3DGenerated

This interface for L3DAttributes enables values to be defined at runtime through the overriding of a single method. In other words, rather than being based on data stored explicitly as attribute values in the database, a generated attribute is one that has values somehow derived from the entry, containing object, or containing context.

L3DPath

This is a utility bean used for addressing contexts, objects, identifiers, and attributes with a simple expressive grammar employing forward slashes, as in:

/<context>/<object>/<identifier>/<attribute>

A path can also be configured with an associated action and application. The class includes methods that apply encoding and decoding on a string representation of the path to make it appropriate for use in URIs. Path beans are available through objects or can be created and defined manually.

L3DException

This class extends the standard Java Exception class and is used to define and manage unexpected behaviors or invalid cases in JLDAP or L3D method execution. On creation, an L3DException accepts numeric identifiers for error codes and/or a textual hint. Numeric identifiers are used to access a general description of the error from localized properties files.

L3D attribute lists

The behavior of an object is configured in part by named lists of attributes, which are typically initialized for an object during construction. The following are the only lists used internally by L3D.

l3d.identify

This list defines the attributes to serve as identifier and name for instances of the object. It must be nontrivially defined for all objects. If the list is assigned only one value, then that attribute serves as both name and identifier. If the list is assigned multiple values, the first attribute serves as the identifier and the second attribute as the name for entries of the object.

l3d.sort

This list defines the attributes that are used in sorting results from a search for entries of the object. If this list is not defined, then no entry sorting is performed. Otherwise, the results of a search will be sorted by comparing the first value of each listed attribute in order unless explicitly instructed not to sort.

SG8 servlet gateway

The package com.mentata.sg8 builds on L3D to enable basic web based gateway interaction with directories through Java servlet containers. It includes servlets that enable authorized users to create, search, modify, or delete entries in a directory database. The gateway implements a single sign-on model via session tracking. All HTML output is generated through JSP. The gateway makes frequent use of HTML hyperlinks between entries, accomplished through servlet calls as L3DPath URIs.

SG8Context

This subclass of L3DContext recognizes additional context-wide configuration options including a style sheet, header/footer include files, mail service parameters, indicators for custom JSP, and a maximum row size for HTML form elements. An SG8 context can also be configured to force authentication or share connections with another context.

SG8Object

This subclass of L3DObject has methods for constructing servlet hyperlinks, controlling the use of formats and actions, and associating display characteristics like a stylesheet, header, footer, custom JSP, or maximum HTML form element row size. Subclasses can also be configured to allow the retrieval of all corresponding entries through glob (i.e. *) identifiers, or to localize labelling based on the language preference of the client's browser.

SG8Makable

This interface for SG8 objects declares placeholder methods for performing pre- and post- processing of requests for entry creation and deletion. It is required for use within the create and delete servlets described in a later section. SG8 objects already contain empty implementations for the methods of this interface, but are not declared to implement the interface by default.

SG8Mutable

This interface for SG8 objects declares placeholder methods for performing pre- and post- processing of requests for entry modifications. It is required for use within the update and link servlets described in a later section. SG8 objects already contain empty implementations for the methods of this interface, but are not declared to implement the interface by default.

SG8Mailable

This interface for SG8 objects declares a method for deriving email destination addresses for entries of an object. It is required for use within the mail servlet described in a later section. SG8 objects already contain an implementation of the method, but are not declared to implement the interface by default.

SG8Attribute

This interface is implemented by all gateway attributes, defining methods to create a hyperlink to the attribute, translate values to HTML, define a separator for between values in HTML output, maintain value count thresholds for HTML output, express/process attribute update HTML form elements, and constrain update interfaces to only allow the augmenting of values.

SG8StringAttribute

This subclass of L3DStringAttribute implements SG8Attribute for strings values.

SG8TextAttribute

This subclass of SG8StringAttribute uses textentry boxes for attribute update form elements with a defined number of rows.

SG8MLSAttribute

This subclass of SG8StringAttribute handles multi-line strings by replacing $ separators with break tags for HTML output.

SG8DiscreteAttribute

This subclass of SG8StringAttribute is assigned a set of possible values. Attribute update form elements will be selection boxes, and new values are checked against permitted ones before being added. Instances can also be configured to display labels in the selection box to hide raw values.

SG8BooleanAttribute

This subclass of SG8DiscreteAttribute allows only values of “TRUE” or “FALSE”.

SG8UTCAttribute

This subclass of SG8StringAttribute represents Universal Time Code date/time signatures that are translated into localized, formatted strings for HTML output. The attribute can be configured to use standard Java date and time styles in formatting.

SG8DateAttribute

This subclass of SG8StringAttribute represents Universal Time Code date/time signatures or date fragments that are translated into localized, formatted strings for HTML output. The attribute can be configured to use standard Java date styles for the formatting.

SG8PasswordAttribute

This subclass of SG8StringAttribute suppresses all displayable output of values. Instances return duplicate password text fields as update form elements, validating a new value by ensuring a match.

SG8ImageAttribute

This subclass of SG8StringAttribute represents URLs that are translated into inline image tags for HTML output. Instances can be configure with a specific width, height, and border, as well as a default URL to use when the attribute is empty.

SG8HTMLBlockAttribute

This subclass of SG8StringAttribute represents a fragment of HTML with an H3 heading line and a paragraph body. Instances generate and process update form elements that allow separate modification of the heading and body text.

SG8EmailAttribute

This subclass of SG8StringAttribute represents email addresses that are translated into spam-protected HTML mailto hyperlinks for HTML output.

SG8URLAttribute

This subclass of SG8StringAttribute represents labelled URLs that are translated into hyperlinks for HTML output, with the option to specify a target window. Instances generate and process update form elements that allow separate modification of the href URL and link text.

SG8ConstantAttribute

This subclass of SG8StringAttribute implements L3DGenerated to reflect a single explicitly defined set of values for all entries.

SG8DnAttribute

This subclass of L3DDnAttribute implements SG8Attribute for distinguished names. It translates values into SG8 hyperlinks to entries of the defined target object for HTML output. Its standard update form elements allow the deletion of values. New values can be added from there through a separate linking process unique to SG8DnAttributes.

SG8SubsetDnAttribute

This subclass of SG8DnAttribute, in its update form elements, restricts selected values to those listed with another distinguished name attribute of the same containing object.

SG8ReverseDnAttribute

This subclass of SG8DnAttribute implements L3DGenerated to derive pointers to all entries of a defined target object that have the containing object's distinguished name as a value in a specified distinguished name attribute.

SG8FilterAttribute

This subclass of SG8DnAttribute implements L3DGenerated to build a compound LDAP search filter using the values of another attribute from the same object as patterns. The resulting filter is then run against a target object and attribute to find matching entries.

SG8NestAttribute

This subclass of SG8DnAttribute translates each value for HTML output to a bulleted paragraph which starts with the standard SG8 hyperlink to the matching entry, then nests the values of a second attribute below. This attribute type can represent a tree with full recursive descent if the second attribute is also a nest attribute.

SG8ReverseNestAttribute

This subclass of SG8NestAttribute implements L3DGenerated to duplicate the reverse distinguished name lookup behavior of SG8ReverseDnAttribute while retaining the nesting of a second attribute's values in HTML output.

Beans

In delivering gateway functionality, SG8 objects are frequently wrapped in invisible beans and stored with the session to enable the transfer of information back and forth between servlets and JSP content. The properties of the beans are accessed and manipulated with the standard Expression Language within JSP content.

SG8Discovery

This bean serves as a basic wrapper for an SG8 object, with properties for the object and the name of a particular attribute along with pseudo properties that enable JSP content to access the object's attributes and attribute lists.

SG8Search

This subclass of SG8Discovery shares the information used for a directory search, including the filter, the total number of matching entries, a desired batch size, the current page, total pages, and the action to which the search results are to be forwarded. The bean uses a pseudo property to iterate through search results, providing access to each entry via the properties inherited from SG8Discovery. It also has properties providing an action hyperlink to the current entry or an implicit SG8Discovery bean.

SG8Change

This subclass of SG8Discovery shares the information used in the modification of a directory entry, including the attributes involved and the results of the adjustments.

JSP

The gateway depends on several JSP files which must be delivered in the same web application archive that invokes gateway servlets under the path /jsp. Each page can be overridden by a custom version in subdirectories named for the context and object to which they are applied. JSP content is called by servlets and makes calls back to servlets in turn. The SG8 JSP does not contain any scriptlets; it makes use of expressions and standard tag libraries as well as a few additional SG8 tags described in a later section. The default SG8 JSP is also internationalized, using formatting actions in place of all visible text and localizing to the language preference of the client's browser where supported. All pages that work with an object employ its assigned stylesheet, header, and footer. Pages remove beans from the session at the end of request processing.

authenticate

This page produces a form for either submitting authentication credentials or removing directory authorization from the session. It expects an L3DPath specifying the context and defining the action which should follow successful authentication.

search

This page produces a form for searching all entries of a given object. It expects an SG8Search representing the object to search and the action to perform on results.

disavow

This page notifies the user that a submitted search found no matches. It expects an SG8Search representing the object and filter for the failed search.

display

This page displays the values of HTML output attributes for an object, or the values of a single specified attribute. It expects an SG8Discovery representing the entry or specific attribute, and employs an SG8 tag to include links to relevant follow-on actions at the bottom.

list

This page displays links to all entries matching a submitted search. It expects an SG8Search comprising the object, a featured attribute, the follow-on action, and the search results.

initialize

This page produces a form for defining the initial attribute values of a new entry. It expects an SG8Discovery representing the object for which a new entry is to be created.

introduce

This page displays a response upon successful entry creation. It expects an SG8Discovery representing the newly created entry. This page serves primarily as a placeholder for alternate responses, since the default page simply forwards the request to the display JSP.

confirm

This page produces a form for confirming the deletion of an entry. It expects an SG8Discovery representing the entry to delete.

modify

This page produces a form for modifying select attribute values of an existing entry. It expects an SG8Discovery representing the entry or specific attribute to change.

recover

This page displays the results of attribute modifications for an entry and provides links to follow-on actions. It expects an SG8Change representing the attributes modified and the outcomes.

associate

This page produces a form for adding or removing values from a distinguished name attribute. It expects an SG8Discovery representing the entry and attribute to modify and an SG8Search representing potential new values found in a search of the attribute's target object.

pick

This page produces a table of links for modifying the updateable distinguished name attributes of an existing entry. It expects an SG8Discovery representing the entry to consider.

seek

This page produces a list of current values and a search form to find new values for a distinguished name attribute. It expects an SG8Discovery representing the entry and attribute to augment as well as an SG8Search representing the attribute's target object.

compose

This page produces a form to draft a textual email message. It expects an SG8Discovery representing the entry and/or attribute from which to derive the destination addresses.

verify

This page displays a response upon successful email delivery. It expects an SG8Discovery representing the entry and/or attribute for which the message was addressed.

fail

This page displays all error messages, any hint, and a stack trace for a failure occurring within the SG8 gateway. It is configured as a JSP error page and expects error data in the page context. The page employs SG8 tags to determine the messages and translate the trace.

Tags

The gateway JSP content makes use of some custom tags to enable functionality that cannot be implemented through standard tags or the Expression Language. They are configured to use the prefix‘sg8. The following tag handlers all extend SimpleTagSupport, they all localize text to the client browser's language preference where supported, none of them make use of the tag body, and all attributes can accept request-time expressions.

ErrorTag

This tag handler is used to throw an exception within JSP content. It has a single action attribute for the error message to pass on. All pages in the gateway that expect beans in the session use the tag to invoke an error state if the requisite beans are not present.

ActionsTag

This tag handler is used to produce hyperlinks to various functions appropriate for an entry. It has action attributes for the populated object and for a specific attribute name. The gateway display page uses the tag to add the links at the tail of the output HTML.

ExcuseTag

This tag handler is used to produce error messages. It has a single action attribute for the exception thrown. The gateway error page uses the tag to add the messages at the top of the output HTML.

TraceTag

This tag handler is used to produce a stack trace for an error. It has a single action attribute for the exception thrown. The gateway error page uses the tag to add the stack trace at the tail of the output HTML for any non-SG8 exception.

ValuesTableTag

This tag handler is used to produce a formatted table of the values of an attribute. It has action attributes for the populated SG8 attribute, the number of columns for the table, and for a table cellspacing dimension. This tag does not appear in any of the standard SG8 JSP content, but could be used in custom versions of the display page.

PaginationTag

This tag handler is used to produce a formatted table of page navigation for a search response matching many entries. It has a single action attribute for the populated SG8 search bean. The gateway list page uses the tag to add pagination to the display of appropriate search results.

SG8Servlet

This abstract subclass of Java standard HttpServlet provides methods to support the use of SG8 contexts and objects to perform transactions with the directory through a servlet container. A method of this class returns named contexts from a central persistent store. Another method translates formatted PATH_INFO strings into parameter information.

For the following subclasses of SG8Servlet, a path first summarizes the grammar for path strings used in servlet requests, and a table then summarizes all parameters with name, description, and indicators for whether each is required (R) and/or multivalued (M). The table is followed by a description of servlet operation.

sign

/sign/<context>/<object>/<identifier>/<attribute>

This servlet enables users to establish an authenticated connection with a directory server and have it stored with their session. If the session is not encrypted, the servlet will throw an exception. If the request does not name a context and object, the servlet will also throw an exception. Otherwise, a corresponding L3DPath bean is constructed and passed through the session to the authenticate JSP, which will in turn send a request back with account binding information or the indicator to sign off as appropriate. If signing on, an authenticated connection is created and stored in the session for use in the other servlets and the request is redirected to the action indicated in the path. If signing off, the authenticated connection is removed from the session and the path is resent to the authenticate JSP.

retrieve

/retrieve/<context>/<object>/<identifier>/<attribute>

This servlet enables users to find and display entries in the database. If the request does not name a context and object, the servlet will throw an exception. If the context is configured to be closed and the session does not contain an authenticated connection to the given context, the path is stored in the session and the request is forwarded to the authenticate JSP. If the input does not define an identifier or filter, a corresponding SG8Search bean is constructed and passed through the session to the search JSP. Otherwise, a filter is configured and the search is performed based on inputs. If nothing is found, the search bean is forwarded to the disavow JSP. Otherwise, if the output is HTML, the results are packed into the search bean and forwarded to either the list JSP for multiple results or the display JSP in the case of a single matching result. If the output is a format other than HTML, the servlet generates the response directly from the results.

create

/create/<context>/<object>/<identifier>

This servlet enables users to create new entries in the database. If the request does not name a context and object, the servlet will throw an exception. If the session does not contain an authenticated connection to the given context the path is stored in the session and the request is forwarded to the authenticate JSP. If the input does not specify an identifier or initial attribute values, a corresponding SG8Discovery bean is constructed and passed through the session to the initialize JSP. Otherwise, a new object is initialized from inputs, verified, and created. The results are packed into an SG8Discovery and are sent to the introduce JSP.

delete

/delete/<context>/<object>/<identifier>

This servlet enables users to delete entries from the database. If the request does not name a context and object, the servlet will throw an exception. If the session does not contain an authenticated connection to the given context the path is stored in the session and the request is forwarded to the authenticate JSP. If the input does not define an identifier, an SG8Search bean is constructed and passed through the session to the search JSP. Otherwise, for a GET request a corresponding SG8Discovery bean is constructed and passed through the session to the confirm JSP. For a POST request, typically from the confirm JSP, the identified entry is deleted and its data is returned to the user as an LDIF file.

update

/update/<context>/<object>/<identifier>/<attribute>

This servlet enables users to update entries by attribute in the database. If the request does not name a context and object, the servlet will throw an exception. If the session does not contain an authenticated connection to the given context the path is stored in the session and the request is forwarded to the authenticate JSP. If the input does not define an identifier, an SG8Search bean is constructed and passed through the session to the search JSP. If an entry is identified but no changes are submitted, an SG8Change bean is constructed and passed through the session to the modify JSP. Otherwise changes received from an update form are processed from the request and each affected attribute is updated. The results are packed into the SG8Change bean and sent to the recover JSP.

link

/link/<context>/<object>/<identifier>/<attribute>/<target>

This servlet enables users to find and add new entries in the database to the values of a distinguished name attribute. If the request does not name a context and object, the servlet will throw an exception. If the session does not contain an authenticated connection to the given context the path is stored in the session and the request is forwarded to the authenticate JSP. If the input does not define an identifier, a corresponding SG8Search bean is constructed and passed through the session to the search JSP. If the input defines an identifier but not an attribute, a corresponding SG8Discovery bean is constructed and passed to the pick JSP. If an attribute is specified but no search criteria or target identifiers, an SG8Change bean for the identified entry and an SG8Search bean for the attribute's target object are constructed and passed to the seek JSP, which will in turn launch a request back to the link servlet with search criteria. The search results are packed into an SG8Search bean and again passed with an SG8Change bean for the identified entry to the associate JSP, which generates an appropriate attribute update form which calls the update servlet directly to make the changes.

mail

/mail/<context>/<object>/<identifier>/<attribute>

This servlet enables users to draft and send textual email messages to addresses derived from entries or attributes in the database. If the request does not name a context and object, the servlet will throw an exception. If the session does not contain an authenticated connection to the given context and the context is closed, the path is stored in the session and the request is forwarded to the authenticate JSP. If the input does not define an identifier, a corresponding SG8Search bean is constructed and passed through the session to the search JSP. If the input defines an identifier, a corresponding SG8Discovery bean is constructed and passed to the compose JSP, which will send a request in turn to the servlet with the contents of the mail message. Destination addresses are derived from the entry or from a given attribute which could either list email addresses explicitly or point through distinguished name values to other entries from which to derive addresses. The servlet attempts to deliver the email, and if successful the object is passed via SG8Discovery bean to the verify JSP.

SG8Exception

This class extends the standard Java Exception class and is used to define and manage unexpected behaviors or invalid cases in SG8 servlet or JSP execution. It wraps JLDAP and L3D exceptions, provides additional localized descriptions of the problem, and is expressed through the error JSP.

SG8 attribute lists

As with L3D, the behavior of an SG8 object is configured in part by named lists of attributes. The following are the lists used within SG8 servlets and JSP content.

sg8.hyperlink

This list defines the attributes necessary to construct an SG8 hyperlink to an entry. It should be nontrivially defined for any SG8 object. To use the default hyperlink behavior, this list should be assigned the same values as the object's l3d.identify attribute list.

sg8.search

This list defines the attributes to offer for filtering in the forms for the default search and seek JSPs. It should be nontrivially defined for any object that is used with these forms.

sg8.sortable

This list defines the attributes to offer for sorting results in the forms for the default search and seek JSPs. Where the list is not defined, no sorting option is presented in these forms.

sg8.highlight

This list defines the attributes to offer for featuring with results in the form for the default search JSP. Where the list is not defined, no feature option is presented in this form.

sg8.list

This list defines the attributes to display per entry by default in HTML results from a retrieve servlet search where multiple entries are found. This attribute list is optional.

sg8.also

This list defines the attributes to offer access to through separate hyperlinks at the bottom of an HTML result from a retrieve servlet search where a single entry is found and displayed. This attribute list is optional.

sg8.r_html

This list defines the attributes to display in order for a result from a retrieve servlet search where a single entry is found and the format is HTML. This attribute list must be nontrivially defined for any SG8 object.

sg8.r_tabtext

This list defines the attributes to display by default in order for results from a retrieve servlet search where the format is tab-delimited text. If this list is not explicitly defined, the value of the relative distinguished name attribute is returned for each entry.

sg8.r_ldif

This list defines the attributes to include by default for results from a retrieve servlet search where the format is LDIF. If this attribute list is not explicitly defined, all accessible attributes for each entry are output with the LDIF.

sg8.r_dsml

This list defines the attributes to include by default for results from a retrieve servlet search where the format is DSML. If this attribute list is not explicitly defined, all accessible attributes for each entry are output with the DSML.

sg8.initialize

This list defines the attributes for which to offer form elements for setting initial values in the default initialize JSP. This attribute list must be nontrivially defined for objects that use the create servlet. Attributes that do not appear on this list will not be processed for initial values prior to entry creation through the create servlet.

sg8.modify

This list defines the attributes for which to offer form elements for adding or altering values in the default modify JSP. This attribute list must be nontrivially defined for objects that use the update servlet. Attributes that do not appear on this list or the associate list below will not be processed for changes through the update servlet.

sg8.associate

This list defines the attributes for which to offer hyperlinks either in the default pick JSP or at the bottom of the default modify JSP. This attribute list is optional, but should generally include any distinguished name attributes which are to updated through the gateway.

sg8.mail

This list defines the attributes needed to derive destination email addresses representing an entry. This attribute list must be nontrivially defined for objects that use the mail servlet. In the default behavior, addresses are deduced from only the first value of this list.

sg8.mailalso

This list defines the attributes from which destination email addresses may be derived. This attribute list is optional, and may contain either attributes that contain email address values or distinguished name attributes that point to entries of a mailable target object.

sg8.keyword

This list defines attributes used to derive keyword metadata to embed in the page representing an entry. This attribute list is optional, but when defined will combine the values of all named attributes into the content for a meta keywords included in the HTML header of the page. Any commas within values are removed.