Web Applications with Javascript or Java: Volume 1: Constraint Validation, Enumerations, Special Datatypes 9783110499957, 9783110499933

This app supports the following operations:

• C
• R
• U
• D

My name is Carly Rae Jepsen. Call me maybe at 1 – 800 – 2437715.

My name is Carly Rae Jepsen. Call me maybe at 1 – 800 – 2437715.

 https://html.spec.whatwg.org/multipage/microdata.html  http://schema.org/

5.4 Excursion: Formalizing Information Models with RDF and OWL

103

Using JSON-LD, as recommended by Google, we need to add a script element of type “application/ld+json” containing the meta-data:

The propositional information expressed with RDFa annotations and JSON-LD corresponds to the following RDF/XML code:

Carly Rae Jepsen 1 – 800 – 2437715

5.4.4 OWL vocabularies and constraints OWL extends RDF by adding many additional language elements for expressing constraints, equalities and derived classes and properties in the context of defining vocabularies. Facts are expressed as in RDF (e. g., with rdf:Description). OWL provides its own predefined language elements for defining classes and properties: 1. The predefined class owl:Class is a subclass of rdfs:Class. 2. The predefined class owl:DatatypeProperty is a subclass of rdf:Property. It classifies attributes. Therefore, the values of an owl:DatatypeProperty are data literals. 3. The predefined class owl:ObjectProperty is a subclass of rdf:Property. It classifies reference properties corresponding to unidirectional binary associations. Since the values of a reference property are object references, the values of an owl:ObjectProperty are object references in the form of resource URIs. We only show with the help of an example that an OWL vocabulary can represent a class diagram more faithfully than the corresponding RDF vocabulary by allowing to express certain constraints. Consider the standard identifier attribute isbn defined in the Book class. In an RDF vocabulary, this attribute is defined in the following way:

104

5 Information Modeling



There are two issues with this RDF definition of an attribute: 1. It doesn’t make it explicit that the property defined is an attribute, and not a reference property. This can only be inferred by finding out that the range class is a datatype, and not an object type. 2. It does not constrain the attribute to have exactly one value, as implied by the defaults of UML class diagram semantics. Using OWL, we can remedy these shortcomings of RDF. The following OWL property definition makes it explicit that the property http://example.org/ex1#isbn is an attribute, while the added OWL restriction defines an “exactly one” cardinality constraint for it:



1

Since the ISBN attribute of the Book class has been designated as the standard identifier attribute in the UML class diagram above, we should define a uniqueness constraint for it. We can do this by including an owl:hasKey element within the class definition:



5.4.5 Usability issues of RDF and OWL Both RDF and OWL have many usability issues. Especially OWL is so difficult to use that most potential users will be discouraged by it. Because OWL was created by a community that is more concerned with formal logic than with information modeling and is not familiar with the concepts and terminology established in information modeling, they have introduced many new unfamiliar terms for concepts that had already been established and named in information modeling. They have even introduced duplicate names within OWL: an attribute

5.5 Summary

105

is in most places called “data property”, but in some places it is called “datatype property” (specifically in OWL/RDF). Usability issues of RDF are: 1. For historical reasons, RDF comes with a strange jargon. Especially, its “subject”“predicate”-“object” terminology sucks. 2. For historical reasons, RDF comes with two different XML namespaces, typically in the from of the two namespace prefixes “rdf” and “rdfs”. The history of a language should not be imposed on its syntax. Users shouldn’t have to bother about which prefix to use. 3. RDF is using the uncommon term “IRI” (as an abbreviation of “International Resource Identifier”), following the unfortunate naming history from “URL” via “URI” to “IRI”, while the What Working Group’s URL Living Standard⁹ has reverted this naming history. 4. For practical purposes, RDF is incomplete: a. it does not make an explicit syntactic distinction between attributes (having a datatype as range) and reference properties (having an object type as range); b. it does not allow expressing simple class definitions, which include mandatory value and single-value constraints, in an RDF vocabulary. OWL is needed for getting these fundamental features. Usability issues of OWL are: 1. it uses an uncommon terminology: e. g., “data property” instead of attribute, “restriction” instead of constraint; 2. some of its elements have confusing names: e. g., “ObjectIntersectionOf” does not denote an intersection of objects, but of object types, and “DataSomeValuesFrom” actually refers to “some data values from”; 3. many of its language elements are kind of unnatural and hard to grasp (much less to remember): e. g., an exactly-one-value property constraint cannot be expressed in the definition of a class along with the property declaration, but requires a separate Restriction element (as shown above).

5.5 Summary 1.

The inception phase of a development project includes problem analysis and requirements engineering. The main goal in this phase is to make a conceptual information model that lays the foundations for the app’s information architecture, which is defined by an implementation-agnostic information design model made in the design phase. Then, in the implementation phase, a platform-specific data

 https://url.spec.whatwg.org/

106

2.

3. 4.

5 Information Modeling

model is derived from the information design model and coded in the platform’s programming language. In the case of an OOP platform, platform-specific data models take the form of class models that are coded as a set of model classes. UML class diagrams provide a visual language for defining an information architecture. Their main building blocks are class rectangles and association lines (connecting class rectangles). A class rectangle has one, two or three compartments, containing the name of the class, its properties, and its methods. An association line connects two classes. The purpose of an association is to classify relationships (links) between objects. In the special case of a unidirectional functional association there is a direct OOP counterpart: a reference property for referencing the objects that are linked to a given object by the association.

5.6 Exercises Consider the problem of managing information about movies, like the Internet Movie Database¹⁰. 1. Describe an illustrative information fragment with the help of some sample data about 3 movies in the form of itemized lists. 2. Turn the itemized lists of sample data into corresponding data tables with table names and suitable column headings. 3. Make a conceptual information model describing movies, then derive an information design model from it and turn it into a JavaScript class model. 4. Finally, code the JavaScript class model in the form of JavaScript model classes.

 http://www.imdb.com/

6 Application Architecture Web application systems, like any other complex engineering artifacts, need an architecture that helps master their complexity by breaking them down into smaller parts with manageable inter-dependencies. Software application architecture is concerned with the following issues: 1. The state structure of the application system to be designed is defined in the form of information models describing its information architecture. 2. The goal of a code base architecture is to structure and partition the overall program code of an application in such a way that the fundamental software quality goal of maintainability is achieved. 3. The distribution of the application system’s runtime components within a computer network is defined by a deployment architecture. A web app is distributed on the Web, which is a world-wide client-server network system with HTTP-based communication. As in all cases of designing a complex system, no matter if a new building, a new space shuttle, a new computer or a new software application is to be designed, an architecture provides a kind of master plan for defining the structure of the system. Any good architecture is based on the following three principles: 1. separation of concerns, which helps managing complexity by breaking a system down into smaller, functionally defined parts such that their 2. interdependencies are minimized, 3. keeping the more fundamental parts independent of the less fundamental parts (the onion principle). Complying with these principles makes it easier to develop, or source, and update certain system parts independently of others. The three most important parts of the code base of an app are: 1. the model, which implements the app’s data model in the form of model classes, defining suitable data structures and constraints; 2. the data storage management procedures, which set up a connection to a storage management system (typically, but not necessarily, an SQL database system) and use it for storing and retrieving persistent data; 3. the user interface (UI) code, taking care of both information provision (or output) to the user, e. g., on the computer screen, and user input provided by user actions in the form of UI events, e. g., keyboard or mouse events, such that all required user interactions are supported. The onion principle requires to keep the app’s model classes independent of – the UI code because it should be possible to re-use the same model classes with different UI technologies; https://doi.org/10.1515/9783110499957-006

108

–

6 Application Architecture

the storage management code because it should be possible to re-use the same model classes with different storage technologies.

However, in many web application frameworks (e. g., in Java EE) the onion principle is violated.

6.1 The Model-View-Controller (MVC) Architecture Metaphor The most popular and most widely used code base architecture approach is the Model-View-Controller code base partitioning pattern. Although it has not been precisely defined, and has been implemented in many different ways, especially in web application frameworks, it is based on the principle of separation of concerns and on the fundamental insight that the model is the foundation for all other parts of an application, in particular for the user interface. Consequently, even if the MVC approach doesn’t provide a precise definition of what a ’model’ is, we can consider it to be a model-based approach.

Figure 6.1 The MVC code base architecture with the model as the foundation.

According to Wikipedia, the first MVC architecture was introduced to application programming with Smalltalk-76 by Trygve Reenskaug¹ in the 1970s. In a later article about Smalltalk-80², MVC is explained as a “three-way division of an application” that entails “separating (1) the parts that represent the model of the underlying application domain from (2) the way the model is presented to the user and from (3) the way the user interacts with it”. The authors, who also use the term “MVC metaphor”, point out that their approach would allow programmers to “write an application model by first defining new classes that would embody the special application domain-specific information”. Notice that the model is defined to consist of classes that capture the required domain information. We call them model classes. In this original MVC approach, there is no well-defined concept of a user interface (UI). The ’view’ is defined as comprising the output side of a UI, only, while the user input side is separated from it and subsumed under the term ’controller’. This does not reflect how a UI is really organized: by combining certain forms of application output with certain forms of user input like two sides of the same coin. A general

 https://en.wikipedia.org/wiki/Trygve_Reenskaug  https://web.archive.org/web/20100921030808/http://www.itu.dk/courses/VOP/E2005/VOP2005E/ 8_mvc_krasner_and_pope.pdf

6.1 The Model-View-Controller (MVC) Architecture Metaphor

109

UI concept includes both the output (the information output provided to the user, as well as system actions) and the input (including information input provided, as well as actions performed, by the user). The Smalltalk MVC metaphor was developed for (monochromatic) text-screenbased user interfaces with no general notion of UI events. This may explain why they did not consider an integral concept of a UI. While they distinguished between the state of objects in the model and their state in the UI, which are both in the scope of a user session, they did not consider the distinction between the model state and the database state. In his web essay GUI Architectures³ (2006), Martin Fowler summarizes the main principles of the original MVC approach in the following way: 1. Separation between UI and model. 2. Divide UI into a ’controller’ and ’view’. 3. Views are synchronized with the model (by means of a data binding mechanism). While the first and third principles are fundamental for the architecture of software applications, the second principle has just a historic meaning and was soon abandoned by the developers of Smalltalk. Compared to the 1980s, computers, human-computer interaction and software application architecture have evolved. In particular, the establishment of the Web as the predominant computing platform has made web browsers to be the most important infrastructure for user interfaces. The MVC terminology is still widely used today, especially by web application frameworks, but with different meanings ascribed to “M”, “V” and “C”. Typically, the “view” denotes the app’s code for the HTML-forms-based user interface, and the “controller” denotes the code that is in charge of mediating between the “view” and the “model”. In many MVC approaches, the “model” is tightly coupled with the underlying database technology, often via an object-relational mapping (ORM) approach mapping classes to tables and objects to table rows. This tight coupling between model classes and database tables violates both the fundamental principle of minimizing interdependencies (because there is no need that model classes depend on database tables) and the onion principle discussed below. For instance, in the Active Record⁴ paradigm of the influential Ruby-on-Rails framework, which has been adopted by many other web application frameworks (such as by CakePHP), the “model” is a direct representation of the schema of the underlying database system, where each entity table of the database is represented by a “model” class that inherits data manipulation methods for performing Create/

 http://martinfowler.com/eaaDev/uiArchs.html  http://martinfowler.com/eaaCatalog/activeRecord.html

110

6 Application Architecture

Retrieve/Update/Delete (CRUD) operations. In this table-to-model-class mapping approach, the “model” depends on the schema of the underlying database and is therefore tightly coupled with the underlying ORM technology. While this may be a suitable approach for a database-first development methodology, where an SQL database is the foundation of an application, it is certainly not a general approach and it turns the model into a secondary asset. Also in frameworks based on ORM annotations, such as Java EE with JPA annotations, the C# framework ASP.NET MVC with Entity Framework and Data Annotations, or the PHP framework Symfony with Doctrine annotations, the “model” is coupled with the underlying ORM technology through the ORM annotations woven into the model class code, thus making the model dependent on the ORM technology used. All these frameworks use the Data Mapper⁵ approach for performing CRUD operations based on ORM annotations.

6.2 The Onion Architecture Metaphor The term “onion architecture” was coined by Jeffry Palermo in a series of blog posts⁶ in 2008. The main principles of this architecture metaphor are (1) to use a hierarchy of dependencies, where less fundamental (or central) parts depend on more fundamental parts, but never the other way around, and (2) the most fundamental part is the model, which implements the application’s data model in the form of model classes while data storage is a separate and less fundamental part that must not be coupled with the model. In fact, Palermo and his followers put a lot more into this architecture metaphor, such as using “repository interfaces” and “service interfaces”, but this is not really essential for the onion metaphor. Also, they are using a different terminology. When they are using the term “domain model” instead of simply model, they are confusing the term “domain model” with “implementation of data model”, which is what model classes do. A data model is derived from an information design model, which may itself be derived from a domain information model. This is the basic development chain in model-based software engineering. In principle, a Data Mapper approach, if it is not based on a platform-specific ORM (annotation) technology, but rather on some form of platform-independent mapping logic, can be used for storage management in an onion architecture.

 http://martinfowler.com/eaaCatalog/dataMapper.html  http://jeffreypalermo.com/blog/the-onion-architecture-part-1/

6.3 “Logical” versus “Physical” User Interface

111

6.3 “Logical” versus “Physical” User Interface The idea of a logical UI model, also called view model, was first proposed (under a different name) by Martin Fowler in his post on the Presentation Model⁷ in 2004, where he stated that the view model “pulls the state and behavior of the view out into a [view] model class”. This means that the logical content of a UI is abstracted out from a concrete “physical” UI, which has specific renderings of the logical UI fields and “commands” (user actions). Logical UI fields are rendered in the form of UI widgets that may have their own state, while logical UI commands are rendered in the form of suitable UI events. Later, in 2005, the view model concept was adopted by John Gossman (from Microsoft) in his blog post Introduction to Model/View/ViewModel pattern for building WPF Apps⁸ and popularized under the architecture pattern acronym “MVVM”. In a user interface for a Create/Retrieve/Update/Delete (CRUD) data management operation, a view model class would be bound to exactly one model class, but could support more than one view (class). A view model class would have properties that are bound to the widgets of the supported view(s), using either one-way or two-way data binding, and methods that are bound to corresponding commands (command binding). Typically, most view fields directly correspond to properties of the underlying model class, although they may have a different name. For these fields (or view model properties), a data binding to the corresponding model properties is needed. But a view model class may also have additional properties, some of them may represent view fields that are not bound to a model class property, while others may represent auxiliary fields that are not shown in the UI. The methods of a view model class are invoked when a corresponding command has been issued by the user through creating a UI event, to which the command has been bound. Dividing up the overall UI code into a view model part and a view part creates a certain overhead that may not be justified in certain cases. While the use of a view model is justified for all apps with CRUD data management operations, it may, for instance, not be justified for visualization user interfaces. The main benefits of view models are that they facilitate: (1) UI design, (2) the testing of the UI logic, and (3) the maintenance of the UI.

 http://martinfowler.com/eaaDev/PresentationModel.html  http://blogs.msdn.com/johngossman/archive/2005/10/08/478683.aspx

112

6 Application Architecture

6.4 MVC Web Applications The MVC terminology is still widely used today, especially by web application frameworks, but with different meanings ascribed to “M”, “V” and “C”. In some approaches it is extended by adding another layer, called “view model” abbreviated by “VM”, which we will discuss later in the course. In the original MVC proposal, the “model” consists of model classes implementing the app’s data model, while today many MV(VM)(C) frameworks do not include any concept of model classes, but rather refer to data objects (or records) as “models”. Also the term “controller” is ambiguous today. In the original MVC proposal, the term “controller” referred to the handling of UI events including user inputs. Today, it typically refers to all the glue code needed for mediating between the model and the view, including the code for routing. In summary, in today’s frameworks, the term “model” vaguely refers to the data sources of an app, while the “view” denotes the app’s code for the user interface, which is based on CSS-styled HTML forms and DOM events, and the “controller” typically denotes the (glue) code that is in charge of mediating between the view and the model. There is widespread agreement that 1. the model should be independent of the view and the controller, implying that the model must neither invoke the view nor the controller (in the model code, there should be no calls of any view or controller procedures); 2. the controller may invoke both the model and the view; 3. the view may invoke the controller. However, as shown in the following diagram, it is not clear if the view may also invoke the model, or if it needs to route any calls of model procedures via the controller. Both approaches are being used in practice. The first approach, where model procedures can be called from the view, is simpler and leads to a leaner controller.

The second approach, where the view is decoupled from the model by routing all calls to it via the controller, is called the mediating-controller MVC approach, shown in the following diagram. It has the advantage of fewer dependencies and providing better support for model-view synchronization based on data-bindings.

6.5 Deployment Architectures

113

In many MVC web application frameworks, the model is tightly coupled with the underlying data storage technology, often via an object-relational mapping (ORM) approach mapping classes to tables and objects to table rows. This tight coupling makes model classes dependent on a specific database technology or even on corresponding database tables. It therefore violates the onion principle, since the model is the most fundamental part of an app, so it must not depend on any other part.

6.5 Deployment Architectures In addition to an information architecture and a code base organization architecture (like MVC), we also have the cross-cutting issue of how to distribute the different parts of an app when it is deployed, so we also need a deployment architecture. Traditionally, most parts of a web app have been executed on back-end computers, while only its HTML/CSS user interface code has been executed on the front-end (or client) side, within a web browser. Today, with the rise of modern JavaScript, we have the option to replace traditional back-end web apps with JavaScript front-end apps, where most parts of the app are executed within a web browser on a frontend device. Such a front-end web app may use either local storage or a (remote) cloud storage service, as illustrated by the two architecture diagrams shown in Figure 6.2.

Figure 6.2 Architectures for front-end web apps

114

6 Application Architecture

In both cases, the JavaScript code of the front-end app is loaded together with its start web page. While using local data storage (with JavaScript’s localStorage or indexedDB APIs) does not require any connection to the Internet after the initial loading of the app, using cloud storage via HTTP messaging with the XMLHttpRequest (XHR) API does require an Internet connection. Typically, but not necessarily, a front-end web app is a single-user application, which is not shared with other users. A back-end web app is a web app where essentially all work is performed by the back-end component, including data validation and user interface page creation. It does not have any front-end component, except the HTML-forms-based, and possibly JS-enriched, user interface pages sent to the user’s front-end computer for being rendered by a web browser. One important task of the controller, especially in back-end apps, is routing: mapping incoming HTTP request messages to a use case of the app, typically represented by a method of a class, such that either the corresponding user interface is provided in the form of a web page or the request message represents the corresponding form submission, which can be directly processed. Today, with NodeJS, we have the option to deploy the JavaScript components of our app either on the back-end or on the front-end, or on both. In the future, due to WebAssembly, the same options may also be available to other programming languages. Web apps that run the same JavaScript code both on the back-end and front-end have been called “universal” (or “isomorphic”). This is especially useful for data validation code because in a responsive constraint validation approach, as discussed in Chapter 7, we validate user data immediately on input in the user interface, but we also validate it on the back-end before save. Modern JavaScript allows truly distributed apps. The two diagrams shown in Figure 6.3 illustrate the distinction between the traditional back-end web app architecture and the new architecture of a (truly) distributed web app.

Figure 6.3 Architectures for back-end and distributed web apps

Part II Constraint Validation For catching various cases of flawed data, we need to define suitable integrity constraints that can be used by the application’s data validation mechanisms. Integrity constraints may take many different forms. The most important type of integrity constraints are property constraints, which define conditions on the admissible property values of an object.

7 Integrity Constraints and Data Validation 7.1 Introduction For detecting non-admissible and inconsistent data and for preventing such data to be added to an application’s database, we need to define suitable integrity constraints that can be used by the application’s data validation mechanisms for catching these cases of flawed data. Integrity constraints are logical conditions that must be satisfied by the data entered by a user and stored in the application’s database. For instance, if an application is managing data about persons including their birth dates and their death dates, then we must make sure that for any person record with a death date, this date is not before that person’s birth date. Since integrity maintenance is fundamental in database management, the data definition language part of the relational database language SQL supports the definition of integrity constraints in various forms. On the other hand, however, there is hardly any support for integrity constraints and data validation in common programming languages such as PHP, Java, C# or JavaScript. It is therefore important to take a systematic approach to constraint validation in web application engineering, like choosing an application development framework that provides sufficient support for it. Unfortunately, many web application development frameworks do not provide sufficient support for defining integrity constraints and performing data validation. Integrity constraints should be defined in one (central) place in an app, and then be used for configuring the user interface and for validating data in different parts of the app, such as in the user interface and in the database. In terms of usability, the goals should be: 1. To prevent the user from entering invalid data in the user interface (UI) by limiting the input options, if possible. 2. To detect and reject invalid user input as early as possible by performing constraint validation in the UI for those UI widgets where invalid user input cannot be prevented by limiting the input options. 3. To prevent that invalid data pollutes the app’s main memory state and persistent database state by performing constraint validation also in the model layer and in the database. HTML5 provides support for validating user input in an HTML-forms-based user interface (UI). Here, the goal is to provide immediate feedback to the user whenever invalid data has been entered into a form field. This UI mechanism of responsive validation is an important feature of modern web applications. In traditional web applications, the back-end component validates the data and returns the validation results in the form of a set of error messages to the front-end. Only then, often several seconds later, and in the hard-to-digest form of a bulk message, does the user get the validation feedback. https://doi.org/10.1515/9783110499957-007

118

7 Integrity Constraints and Data Validation

7.2 Integrity Constraints Integrity constraints (or simply constraints) are logical conditions on the data of an app. They may take many different forms. The most important type of constraints, property constraints, define conditions on the admissible property values of an object. They are defined for an object type (or class) such that they apply to all objects of that type. We concentrate on the most important cases of property constraints:

String Length Constraints

require that the length of a string value for an attribute is less than a certain maximum number, or greater than a minimum number.

Mandatory Value Constraints

require that a property must have a value. For instance, a person must have a name, so the name attribute must not be empty.

Range Constraints

require that an attribute must have a value from the value space of the type that has been defined as its range. For instance, an integer attribute must not have the value “aaa”

Interval Constraints

require that the value of a numeric attribute must be in a specific inteval.

Pattern Constraints

require that a string attribute’s value must match a certain pattern defined by a regular expression.

Cardinality Constraints

apply to multi-valued properties, only, and require that the cardinality of a multi-valued property’s value set is not less than a given minimum cardinality or not greater than a given maximum cardinality.

Uniqueness Constraints require that a property’s value is unique among all instances of the given object type. Referential Integrity Constraints

require that the values of a reference property refer to an existing object in the range of the reference property.

Frozen Value Constraints

require that the value of a property must not be changed after it has been assigned initially.

The visual language of UML class diagrams supports defining integrity constraints either in a special way for special cases (like with predefined keywords), or, in the general case, with the help of invariants, which are conditions expressed either in plain English or in the Object Constraint Language (OCL) and shown in a special type of rectangle attached to the model element concerned. We use UML class diagrams for modeling constraints in design models that are independent of a specific programming language or technology platform. UML class diagrams provide special support for expressing multiplicity (or cardinality) constraints. This type of constraint allows to specify a lower multiplicity (minimum cardinality) or an upper multiplicity (maximum cardinality), or both, for a property or an association end. In UML, this takes the form of a multiplicity expression l..u where the lower multiplicity l is a non-negative integer and the upper multiplicity u is either a positive integer not smaller than l or the special value *

7.2 Integrity Constraints

119

standing for unbounded. For showing property multiplicity (or cardinality) constrains in a class diagram, multiplicity expressions are enclosed in brackets and appended to the property name, as shown in the Person class rectangle below. In the following sections, we discuss the different types of property constraints listed above in more detail. We also show how to express some of them in computational languages such as UML class diagrams, SQL table creation statements, JavaScript model class definitions, or the annotation-based languages Java Bean Validation annotations and ASP.NET Data Annotations. Any systematic approach to constraint validation also requires to define a set of error (or ’exception’) classes, including one for each of the standard property constraints listed above.

7.2.1 String Length Constraints The length of a string value for a property such as the title of a book may have to be constrained, typically rather by a maximum length, but possibly also by a minimum length. In an SQL table definition, a maximum string length can be specified in parenthesis appended to the SQL datatype CHAR or VARCHAR, as in VARCHAR(50). UML does not define any special way of expressing string length constraints in class diagrams. Of course, we always have the option to use an invariant for expressing any kind of constraint, but it seems preferable to use a simpler form of expressing these property constraints. One option is to append a maximum length, or both a minimum and a maximum length, in parenthesis to the datatype name, like so

Another option is to use min/max constraint keywords in the property modifier list:

7.2.2 Mandatory Value Constraints A mandatory value constraint requires that a property must have a value. This can be expressed in a UML class diagram with the help of a multiplicity constraint expression where the lower multiplicity is 1. For a single-valued property, this would result in the multiplicity expression 1..1, or the simplified expression 1, appended to the

120

7 Integrity Constraints and Data Validation

property name in brackets. For example, the following class diagram defines a mandatory value constraint for the property name:

Whenever a class rectangle does not show a multiplicity expression for a property, the property is mandatory (and single-valued), that is, the multiplicity expression 1 is the default for properties. In an SQL table creation statement, a mandatory value constraint is expressed in a table column definition by appending the key phrase NOT NULL to the column definition as in the following example: CREATE TABLE persons( name VARCHAR(30) NOT NULL, age INTEGER )

According to this table definition, any row of the persons table must have a value in the column name, but not necessarily in the column age. In JavaScript, we can code a mandatory value constraint by a class-level check function that tests if the provided argument evaluates to a value, as illustrated in the following example: Person.checkName = function (n) { if (n === undefined) { return "A name must be provided!"; // constraint violation error message } else return ""; // no constraint violation };

With Java Bean Validation, a mandatory property like name is annotated with NotNull in the following way: @Entity public class Person { @NotNull private String name; private int age; }

The equivalent ASP.NET Data Annotation is Required as shown in

7.2 Integrity Constraints

121

public class Person{ [Required] public string name { get; set; } public int age { get; set; } }

7.2.3 Range Constraints A range constraint requires that a property must have a value from the value space of the type that has been defined as its range. This is implicitly expressed by defining a type for a property as its range. For instance, the attribute age defined for the object type Person in the class diagram above has the range Integer, so it must not have a value like “aaa”, which does not denote an integer. However, it may have values like -13 or 321, which also do not make sense as the age of a person. In a similar way, since its range is String, the attribute name may have the value “” (the empty string), which is a valid string that does not make sense as a name. We can avoid allowing negative integers like -13 as age values, and the empty string as a name, by assigning more specific datatypes as range to these attributes, such as NonNegativeInteger to age, and NonEmptyString to name. Notice that such more specific datatypes are neither predefined in SQL nor in common programming languages, so we have to implement them either in the form of user-defined types, as supported in SQL-99 database management systems such as PostgreSQL, or by using suitable additional constraints such as interval constraints, which are discussed in the next section. In a UML class diagram, we can simply define NonNegativeInteger and NonEmptyString as custom datatypes and then use them in the definition of a property, as illustrated in the following diagram:

In JavaScript, we can code a range constraint by a check function, as illustrated in the following example: Person.checkName = function (n) { if (typeof(n) !== "string" || n.trim() === "") { return "Name must be a non-empty string!"; } else return ""; };

This check function detects and reports a constraint violation if the given value for the name property is not of type “string” or is an empty string. In a Java EE web app, for declaring empty strings as non-admissible user input we must set the context parameter

122

7 Integrity Constraints and Data Validation

javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL

to true in the web deployment descriptor file web.xml. In ASP.NET, empty strings are non-admissible by default.

7.2.4 Interval Constraints An interval constraint requires that an attribute’s value must be in a specific interval, which is specified by a minimum value or a maximum value, or both. Such a constraint can be defined for any attribute having an ordered type, but normally we define them only for numeric datatypes or calendar datatypes. For instance, we may want to define an interval constraint requiring that the age attribute value must be in the interval [25,70]. In a class diagram, we can define such a constraint by using the property modifiers min and max, as shown for the age attribute of the Driver class in the following diagram.

In an SQL table creation statement, an interval constraint is expressed in a table column definition by appending a suitable CHECK clause to the column definition as in the following example: CREATE TABLE drivers( name VARCHAR NOT NULL, age INTEGER CHECK (age >= 25 AND age 3) { return "There must be no more than 3 nicknames!"; } else return ""; };

With Java Bean Validation annotations, we can specify @Size( max=3) List nickNames @Size( min=3, max=5) List members

7.2.7 Uniqueness Constraints A uniqueness constraint (or key constraint) requires that a property’s value (or the value list of a list of properties in the case of a composite key constraint) is unique among all instances of the given object type. For instance, in a UML class diagram with the object type Book we can define the isbn attribute to be unique, or, in other words, a key, by appending the (user-defined) property modifier keyword key in curly braces to the attribute’s definition in the Book class rectangle shown in the following diagram.

In an SQL table creation statement, a uniqueness constraint is expressed by appending the keyword UNIQUE to the column definition as in the following example:

126

7 Integrity Constraints and Data Validation

CREATE TABLE books( isbn VARCHAR(10) NOT NULL UNIQUE, title VARCHAR(50) NOT NULL )

In JavaScript, we can code this uniqueness constraint by a check function that tests if there is already a book with the given isbn value in the books table of the app’s database.

7.2.8 Standard Identifiers (Primary Keys) An unique attribute (or a composite key) can be declared to be the standard identifier for objects of a given type, if it is mandatory (or if all attributes of the composite key are mandatory). We can indicate this in a UML class diagram with the help of the property modifier id appended to the declaration of the attribute isbn as shown in the following diagram.

Notice that such a standard identifier declaration implies both a mandatory value and a uniqueness constraint on the attribute concerned. Standard identifiers are called primary keys in relational databases. We can declare an attribute to be the primary key in an SQL table creation statement by appending the phrase PRIMARY KEY to the column definition as in the following example: CREATE TABLE books( isbn VARCHAR(10) PRIMARY KEY, title VARCHAR(50) NOT NULL )

In JavaScript, we cannot easily code a standard identifier declaration, because this would have to be part of the metadata of the class definition, and there is no standard support for such metadata in JavaScript. However, we should at least check if the given argument violates the implied mandatory value or uniqueness constraints by invoking the corresponding check functions discussed above.

7.2.9 Referential Integrity Constraints A referential integrity constraint requires that the values of a reference property refer to an object that exists in the population of the property’s range class. Since we do

7.2 Integrity Constraints

127

not deal with reference properties in this chapter, we postpone the discussion of referential integrity constraints to Volume 2.

7.2.10 Frozen and Read-Only Value Constraints A frozen value constraint defined for a property requires that the value of this property must not be changed after it has been assigned. This includes the special case of read-only value constraints on mandatory properties that are initialized at object creation time. Typical examples of properties with a frozen value constraint are standard identifier attributes and event properties. In the case of events, the semantic principle that the past cannot be changed prohibits that the property values of events can be changed. In the case of a standard identifier attribute we may want to prevent users from changing the ID of an object since this requires that all references to this object using the old ID value are changed as well, which may be difficult to achieve (even though SQL provides special support for such ID changes by means of its ON UPDATE CASCADE clause for the change management of foreign keys). The following diagram shows how to define a frozen value constraint for the isbn attribute:

In Java, a read-only value constraint can be enforced by declaring the property to be final. In JavaScript, a read-only property slot can be implemented as in the following example: Object.defineProperty( obj, "teamSize", {value: 5, writable: false, enumerable: true})

where the property slot obj.teamSize is made unwritable. An entire object obj can be frozen with Object.freeze( obj). We can implement a frozen value constraint for a property in the property’s setter method like so: Book.prototype.setIsbn = function (i) { if (this.isbn === undefined) this.isbn = i; else console.log("Attempt to re-assign a frozen property!"); }

128

7 Integrity Constraints and Data Validation

7.2.11 Beyond property constraints So far, we have only discussed how to define and check property constraints. However, in certain cases there may be also integrity constraints that do not just depend on the value of a particular property, but rather on 1. the values of several properties of a particular object (object-level constraints), 2. the value of a property before and its value after a change attempt (dynamic constraints), 3. the set of all instances of a particular object type (type-level constraints), 4. the set of all instances of several object types. OCL The Object Constraint Language (OCL) was defined in 1997 as a formal logic language for expressing integrity constraints in UML version 1.1. Later, it was extended for allowing to define also (1) derivation expressions for defining derived properties, and (2) preconditions and postconditions for operations, in a class model.

In a class model, property constraints can be expressed within the property declaration line in a class rectangle (typically with keywords, such as id, max, etc.). For expressing more complex constraints, such as object-level or type-level constraints, we can attach an invariant declaration box to the class rectangle(s) concerned and express the constraint either in (unambiguous) English or in the Object Constraint Language (OCL). A simple example of an object-level constraint expressed as an OCL invariant is shown in Figure 7.1.

Figure 7.1 An example of an object-level constraint

A general approach for implementing object-level constraint validation consists of taking the following steps: 1. Choose a fixed name for an object-level constraint validation function, such as validate. 2. For any class that needs object-level constraint validation, define a validate function returning either a ConstraintViolation or a NoConstraintViolation object. 3. Call this function, if it exists, for the given model class,

7.3 Responsive Validation

129

a. in the UI/view, on form submission; b. in the model class, before save, both in the create and in the update method. Constraints affecting two or more model classes could be defined in the form of static methods (in a model layer method library) that are invoked from the object-level validation methods of the affected model classes.

7.3 Responsive Validation This problem is well-known from classical web applications where the front-end component submits the user input data via HTML form submission to a back-end component running on a remote web server. Only this back-end component validates the data and returns the validation results in the form of a set of error messages to the front-end. Only then, often several seconds later, and in the hard-to-digest form of a bulk message, does the user get the validation feedback. This approach is no longer considered acceptable today. Rather, in a responsive validation approach, the user should get immediate validation feedback on each single data input. Technically, this can be achieved with the help of event handlers for the user interface events input or change. Responsive validation requires a data validation mechanism in the user interface (UI), such as the HTML5 form validation API². Alternatively, the jQuery Validation Plugin³ can be used as a (non-HTML5-based) form validation API. The HTML5 form validation API essentially provides new types of input fields (such as number or date) and a set of new attributes for form control elements for the purpose of supporting responsive validation performed by the browser. Since using the new validation attributes (like required, min, max and pattern) implies defining constraints in the UI, they are not really useful in a general approach where constraints are only checked, but not defined, in the UI. Consequently, we only use two methods of the HTML5 form validation API for validating constraints in the HTML-forms-based user interface of our app. The first of them, setCustomValidity, allows to mark a form field as either valid or invalid by assigning either an empty string or a non-empty (constraint violation) message string. The second method, checkValidity, is invoked on a form before user input data is committed or saved (for instance with a form submission). It tests, if all fields have a valid value. For having the browser automatically displaying any constraint

 http://www.html5rocks.com/en/tutorials/forms/constraintvalidation/  http://jqueryvalidation.org/

130

7 Integrity Constraints and Data Validation

violation messages, we need to have a submit event, even if we don’t really submit the form, but just use a save button. See this Mozilla tutorial⁴ or this HTML5Rocks tutorial⁵ for more about the HTML5 form validation API.

7.4 Constraint Validation in MVC Applications Integrity constraints should be defined in the model classes of an MVC app since they are part of the business semantics of a model class (representing a business object type). However, a more difficult question is where to perform data validation? In the database? In the model classes? In the controller? Or in the user interface (“view”)? Or in all of them? A relational database management system (DBMS) performs data validation whenever there is an attempt to change data in the database, provided that all relevant integrity constraints have been defined in the database. This is essential since we want to avoid, under all circumstances, that invalid data enters the database. However, it requires that we somehow duplicate the code of each integrity constraint, because we want to have it also in the model class to which the constraint belongs. Also, if the DBMS would be the only application component that validates the data, this would create a latency, and hence usability, problem in distributed applications because the user would not get immediate feedback on invalid input data. Consequently, data validation needs to start in the user interface (UI). However, it is not sufficient to perform data validation in the UI. We also need to do it in the model classes, and in the database, for making sure that no flawed data enters the application’s persistent data store. This creates the problem of how to maintain the constraint definitions in one place (the model), but use them in two or three other places (at least in the model classes and in the UI code, and possibly also in the database).We call this the multiple validation problem. This problem can be solved in different ways. For instance: 1. Define the constraints in a declarative language (such as Java Bean Validation Annotations or ASP.NET Data Annotations) and generate the back-end/model and front-end/UI validation code both in a back-end application programming language such as Java or C#, and in JavaScript. 2. Keep your validation functions in the (PHP, Java, C# etc.) model classes on the back-end, and invoke them from the JavaScript UI code via XHR. This approach can only be used for specific validations, since it implies the penalty of an additional HTTP communication latency for each validation invoked in this way.

 https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation  http://www.html5rocks.com/en/tutorials/forms/constraintvalidation/

7.5 Adding Constraints to a Design Model

3.

131

Use JavaScript as your back-end application programming language (such as with NodeJS), then you can code your validation functions in your JavaScript model classes on the back-end and execute them both before committing changes on the back-end and on user input and form submission in the UI on the front-end side.

The simplest, and most responsive, solution is the third one, using only JavaScript both for the back-end and front-end components of a web app.

7.5 Adding Constraints to a Design Model We again consider the book data management problem that was considered in Part 1. But now we also consider the data integrity rules (or ’business rules’) that govern the management of book data. These integrity rules, or constraints, can be expressed in a UML class diagram as shown in Figure 7.2 below.

Figure 7.2 A design model defining the object type Book with two invariants

1. 2. 3.

4.

In this model, the following constraints have been expressed: Due to the fact that the isbn attribute is declared to be the standard identifier of Book, it is mandatory and unique. The isbn attribute has a pattern constraint requiring its values to match the ISBN-10 format that admits only 10-digit strings or 9-digit strings followed by “X”. The title attribute is mandatory, as indicated by its multiplicity expression [1], and has a string length constraint requiring its values to have at most 50 characters. The year attribute is mandatory and has an interval constraint, however, of a special form since the maximum is not fixed, but provided by the calendar function nextYear(), which we implement as a utility function.

Notice that the edition attribute is not mandatory, but optional, as indicated by its multiplicity expression [0..1]. In addition to the constraints described in this list, there are the implicit range constraints defined by assigning the datatype NonEmptyString as range to isbn and title, Integer to year, and PositiveIn-

132

7 Integrity Constraints and Data Validation

teger to edition. In our plain JavaScript approach, all these property constraints are coded in the model class within property-specific check functions. The meaning of the design model can be illustrated by a sample data population respecting all constraints: Table 7.1 Sample data for Book ISBN

Title

Year

Edition

X  

Weaving the Web Gödel, Escher, Bach I Am A Strange Loop

  

 

7.6 Summary 1.

2. 3. 4.

5. 6.

7.

Constraints are logical conditions on the data of an app. The simplest, and most important, types of constraints are property constraints and object-level constraints. Constraints should be defined in the model classes of an MVC app, since they are part of their business semantics. Constraints should be checked in various places of an MVC app: in the UI/view code, in model classes, and possibly in the database. Software applications that include CRUD data management need to perform two kinds of bi-directional object-to-string type conversions: a. Between the model and the UI: converting model object property values to UI widget values, and, the other way around, converting input widget values to property values. Typically, widgets are form fields that have string values. b. Between the model and the datastore: converting model objects to storage data sets (called serialization), and, the other way around, converting storage data sets to model objects (called de-serialization). This involves converting property values to storage data values, and, the other way around, converting storage data values to property values. Typically, datastores are either JavaScript’s local storage or IndexedDB, or SQL databases, and objects have to be mapped to some form of table rows. In the case of an SQL database, this is called “Object-Relational Mapping” (ORM). Do not perform any string-to-property-value conversion in the UI code. Rather, this is the business of the model code. For being able to observe how an app works, or, if it does not work, where it fails, it is essential to log all critical application events, such as data retrieval, save and delete events, at least in the JavaScript console. Responsive validation means that the user, while typing, gets immediate validation feedback on each input (keystroke), and when requesting to save the new data.

7.8 Quiz Questions

133

7.7 Criteria for Evaluating the Validation Support of Frameworks The support of MVC frameworks for constraint validation can be evaluated according to the following criteria. Does the framework support 1. the declaration of all important kinds of property constraints as defined above (String Length Constraints, Mandatory Value Constraints, Range Constraints, etc.) in model classes? 2. the provision of an object validation function to be invoked in the UI on form submission, and in the model layer before save? 3. validation in the model class on assign and before save? 4. informative generic validation error messages referring to the object and property concerned? 5. custom validation error messages with parameters? 6. responsive validation in the user interface on input and on submit based on the constraints defined in the model classes, preferably using the HTML5 constraint validation API, or at least a general front-end API like the jQuery Validation Plugin? 7. two-fold validation with defining constraints in the model and checking them in the model and in the view? 8. three-fold validation with defining constraints in the model and checking them in the model, the view and in the database system? 9. reporting database validation errors that are passed from the database system to the app?

7.8 Quiz Questions If you would like to look up the answers for the following quiz questions, you can check our discussion forum⁶. If you don’t find an answer in the forum, you may create a post asking for an answer to a particular question.

7.8.1 Question 1: Where to check constraints Where in the application code should the constraints be checked? In the … ☐ controller code ☐ model classes ☐ user interface code ☐ underlying DBMS (if it supports constraint validation)

 http://web-engineering.info/forum/12

134

7 Integrity Constraints and Data Validation

7.8.2 Question 2: Where to define constraints Where in the application code should the constraints be defined? In the … ☐ controller code ☐ model classes ☐ user interface HTML5 code ☐ user interface JavaScript code

7.8.3 Question 3: Counting constraints

How many constraints are specified by the class model shown in the diagram? Enter a number: _____

7.8.4 Question 4: Constraint names

Which of the following constraints are specified by the class model? ☐ A range constraint for the property name. ☐ A uniqueness constraint for the property name. ☐ A referential integrity constraint for the property name. ☐ A uniqueness constraint for the property age. ☐ A mandatory value constraint for the property name. ☐ A mandatory value constraint for the property age.

7.8 Quiz Questions

135

7.8.5 Question 5: Compliant objects

Which of the following objects do not represent admissible instances (or, in other words, violate a constraint) of the object type Person? ☐ {name: "Susan", age: 8} ☐ {name: " ", age: 0} ☐ {name: "Susan"} ☐ {name: "Peter", age: 122}

8 Implementing Constraint Validation in a Plain JS Web App 8.1 Introduction The minimal JavaScript front-end web application that we have discussed in Chapter 3 has been limited to support the minimum functionality of a data management app only. For instance, it did not take care of preventing the user from entering invalid data into the app’s database. In this chapter, we show how to express integrity constraints in a JavaScript model class, and how to perform constraint validation both in the model part of the app and in the user interface built with HTML5. We show how to perform responsive validation with the HTML5 form validation API¹. Since using the new HTML5 input field types and validation attributes (like required, min, max and pattern) implies defining constraints in the UI, they are not really useful in a best-practice approach where constraints are only checked, but not defined, in the UI. Consequently, we will not use the new HTML5 features for defining constraints in the UI, but only use two methods of the HTML5 form validation API: 1. setCustomValidity, which allows to mark a form field as either valid or invalid by assigning either an empty string or a non-empty (constraint violation) message string; 2. checkValidity, which is invoked on a form before user input data is committed or saved (for instance with a form submission); it tests, if all fields have a valid value. In the case of two special kinds of attributes, having calendar dates or colors as values, it is desirable to use the new UI widgets defined by HTML5 for picking a date or picking a color (with corresponding input field types). Unfortunately, in 2017, the HTML5 date picker widget is still not supported by all major browsers.

8.2 New Issues Compared to the Minimal App² discussed in Chapter 3 we have to deal with a number of new issues: 1. In the model code we have to add for every property of a class a. a check function that can be invoked for validating the constraints defined for the property, and

 https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation  http://web-engineering.info/tech/JsFrontendApp/MinimalApp/index.html https://doi.org/10.1515/9783110499957-008

8.3 Make a JavaScript Class Model

2.

137

b. a setter method that invokes the check function and is to be used for setting the value of the property. In the user interface (“view”) code we have to take care of a. responsive validation on user input for providing immediate feedback to the user, b. validation on form submission for preventing the submission of flawed data to the model layer.

For improving the break-down of the view code, we introduce a utility method (in lib/util.js) that fills a select form control with option elements the contents of which is retrieved from an entity table such as Book.instances. This method is used in the setupUserInterface method of both the updateBook and the deleteBook use cases. Checking the constraints in the user interface (UI) on user input is important for providing immediate feedback to the user. But it is not safe enough to perform constraint validation only in the UI, because this could be circumvented in a distributed web application where the UI runs in the web browser of a front-end device while the application’s data is managed by a back-end component on a remote web server. Consequently, we need multiple constraint validation, first in the UI on input (or on change) and on form submission, and subsequently in the model layer before saving/sending data to the persistent data store. And in an application based on a DBMS we may also use a third round of validation before persistent storage by using the validation mechanisms of the DBMS. This is a must, when the application’s database is shared with other apps. Our proposed solution to this multiple validation problem is to keep the constraint validation code in special check functions in the model classes and invoke these functions both in the UI on user input and on form submission, as well as in the create and update data management methods of the model class via invoking the setters. Notice that referential integrity constraints (and other relationship constraints) may also be violated through a delete operation, but in our single-class example we don’t have to consider this.

8.3 Make a JavaScript Class Model Using the information design model shown in Figure 7.2 above as the starting point, we make a JavaScript class model by performing the following steps: 1. Create a check operation for each (non-derived) property in order to have a central place for implementing all the constraints that have been defined for a property in the design model. For a standard identifier attribute, such as Book:: isbn, two check operations are needed:

138

8 Implementing Constraint Validation in a Plain JS Web App

A basic check operation, such as checkIsbn, for checking all basic constraints of the attribute, except the mandatory value and the uniqueness constraints. b. An extended check operation, such as checkIsbnAsId, for checking, in addition to the basic constraints, the mandatory value and uniqueness constraints that are required for a standard identifier attribute. The checkIsbnAsId operation is invoked on user input for the isbn form field in the create book form, and also in the setIsbn method, while the checkIsbn operation can be used for testing if a value satisfies the syntactic constraints defined for an ISBN. Create a setter operation for each (non-derived) single-valued property. In the setter, the corresponding check operation is invoked and the property is only set, if the check does not detect any constraint violation. a.

2.

This leads to the JavaScript class model shown on the right-hand side of the mapping arrow in the following figure.

Figure 8.1 From an information design model to a JS class model

Essentially, the JavaScript class model extends the design model by adding checks and setters for each property. The attached invariants have been dropped since they are taken care of in the checks. Property ranges have been turned into JavaScript datatypes (with a reminder to their real range in curly braces). Notice that the names of check functions are underlined, since this is the convention in UML for class-level (as opposed to instance-level) operations.

8.4 Set up the Folder Structure Adding Some Library Files

139

8.4 Set up the Folder Structure Adding Some Library Files The MVC folder structure of our validation app extends the structure of the minimal app by adding a lib folder containing the generic code libraries browserShims. js, errorTypes.js and util.js. Thus, we get the following folder structure: publicLibrary css main.css normalize.min.css lib browserShims.js errorTypes.js util.js src c m v index.html

We discuss the contents of the added files in the following sub-sections.

8.4.1 Provide general utility functions and JavaScript fixes in library files We add three library files to the lib folder: 1. browserShims.js contains a definition of the string trim function for older browsers that don’t support this function (which was only added to JavaScript in ES5, defined in 2009). More browser shims for other recently defined functions, such as querySelector and classList, could also be added to browserShims.js. 2. util.js contains the definitions of a few utility functions such as isNonEmptyString(x) for testing if x is a non-empty string. 3. errorTypes.js defines classes for error (or exception) types corresponding to the basic types of property constraints discussed above: StringLengthConstraintViolation, MandatoryValueConstraintViolation, RangeConstraintViolation, IntervalConstraintViolation, PatternConstraintViolation, UniquenessConstraintViolation. In addition, a class NoConstraintViolation is defined for being able to return a validation result object in the case of no constraint violation.

8.4.2 Create a start page The start page index.html takes care of loading CSS page styling files with the help of the following two link elements:

140

8 Implementing Constraint Validation in a Plain JS Web App



Then it loads the following JavaScript files: 1. browserShims.js and util.js from the lib folder, discussed in Section 4.1, 2. errorTypes.js from the lib folder, defining exception classes. 3. initialize.js from the src/c folder, defining the app’s MVC namespaces, as discussed in Chapter 3 4. Book.js from the src/m folder, a model class file that provides data management and other functions discussed in Section 5.

8.5 Write the Model Code The JavaScript class model shown on the right hand side in Figure 8.1 can be coded step by step for getting the code of the model layer of our JavaScript front-end app. These steps are summarized in the following section.

8.5.1 Summary 1. 2.

3.

4.

Code the model class as a JavaScript constructor function. Code the check functions, such as checkIsbn or checkTitle, in the form of class-level (’static’) methods. Take care that all constraints, as specified in the JavaScript class model, are properly coded in the check functions. Code the setter operations, such as setIsbn or setTitle, as (instance-level) methods. In the setter, the corresponding check operation is invoked and the property is only set, if the check does not detect any constraint violation. Code the add and remove operations, if there are any, as instance-level methods.

These steps are discussed in more detail in the following sections.

8.5.2 Code the model class as a constructor function The class Book is coded as a corresponding constructor function with the same name Book such that all its (non-derived) properties are supplied with values from corresponding key-value slots of a slots parameter. function Book( slots) { // assign default values this.isbn = ""; // string this.title = ""; // string

8.5 Write the Model Code

141

this.year = 0; // number (int) // set properties only if constructor is invoked with an argument if (arguments.length > 0) { this.setIsbn( slots.isbn); this.setTitle( slots.title); this.setYear( slots.year); // optional property if (slots.edition) this.setEdition( slots.edition); } };

In the constructor body, we first assign default values to the class properties. These values will be used when the constructor is invoked as a default constructor (without arguments), or when it is invoked with only some arguments. It is helpful to indicate the range of a property in a comment. This requires to map the platform-independent datatypes of the information design model to the corresponding implicit JavaScript datatypes according to the following table. Table 8.1 Datatype mapping Platform-independent datatype

JavaScript datatype

SQL

String Integer Decimal Boolean Date

string number (int) number (float) boolean Date

CHAR(n) or VARCHAR(n) INTEGER REAL, DOUBLE PRECISION or DECIMAL(p,s) BOOLEAN DATE

Since the setters may throw constraint violation errors, the constructor function, and any setter, should be called in a try-catch block where the catch clause takes care of processing errors (at least logging suitable error messages). As in the minimal app, we add a class-level property Book.instances representing the collection of all Book instances managed by the app in the form of an entity table: Book.instances = {};

8.5.3 Code the property checks Code the property check functions in the form of class-level (’static’) methods. In JavaScript, this means to define them as method slots of the constructor, as in Book.checkIsbn (recall that a constructor is a JS object, since in JavaScript, functions are objects, and as an object, it can have slots). Take care that all constraints of a property as specified in the class model are properly coded in its check function. This concerns, in particular, the mandatory

142

8 Implementing Constraint Validation in a Plain JS Web App

value and uniqueness constraints implied by the standard identifier declaration (with {id}), and the mandatory value constraints for all properties with multiplicity 1, which is the default when no multiplicity is shown. If any constraint is violated, an error object instantiating one of the error classes listed above in Section 4.1 and defined in the file errorTypes.js is returned. For instance, for the checkIsbn operation we obtain the following code: Book.checkIsbn = function (id) { if (!id) { return new NoConstraintViolation(); } else if (typeof id !== "string" || id.trim() === "") { return new RangeConstraintViolation( "The ISBN must be a non-empty string!"); } else if (!/\b\d{9}(\d|X)\b/.test( id)) { return new PatternConstraintViolation( "The ISBN must be a 10-digit string or "+ " a 9-digit string followed by 'X'!"); } else { return new NoConstraintViolation(); } };

Notice that, since isbn is the standard identifier attribute of Book, we only check the syntactic constraints in checkIsbn, but we check the mandatory value and uniqueness constraints in checkIsbnAsId, which itself first invokes checkIsbn: Book.checkIsbnAsId = function (id) { var constraintViolation = Book.checkIsbn( id); if ((constraintViolation instanceof NoConstraintViolation)) { if (!id) { constraintViolation = new MandatoryValueConstraintViolation( "A value for the ISBN must be provided!"); } else if (Book.instances[id]) { constraintViolation = new UniquenessConstraintViolation( "There is already a book record with this ISBN!"); } else { constraintViolation = new NoConstraintViolation(); } } return constraintViolation; };

We assume that all check functions and setters can deal both with proper data values (that are of the attribute’s range type) and also with string values that are supposed to represent proper data values, but have not yet been converted to the attribute’s range type. We take this approach for avoiding datatype conversions in the user interface (“view”) code. Notice that all data entered by a user in an HTML form field is of type String and must be converted (or de-serialized) before its validity can be

8.5 Write the Model Code

143

checked and it can be assigned to the corresponding property. It is preferable to perform these type conversions in the model code, and not in the user interface code.. For instance, in our example app, we have the integer-valued attribute year. When the user has entered a value for this attribute in a corresponding form field, in the Create or Update user interface, the form field holds a string value. This value is passed to the Book.add or Book.update method, which invokes the setYear and checkYear methods. Only after being validated, this string value is converted to an integer and assigned to the year attribute.

8.5.4 Code the property setters Code the setter operations as (instance-level) methods. In the setter, the corresponding check function is invoked and the property is only set, if the check does not detect any constraint violation. Otherwise, the constraint violation error object returned by the check function is thrown. For instance, the setIsbn operation is coded in the following way: Book.prototype.setIsbn = function (id) { var validationResult = Book.checkIsbnAsId( id); if (validationResult instanceof NoConstraintViolation) { this.isbn = id; } else { throw validationResult; } };

There are similar setters for the other properties (title, year and edition).

8.5.5 Add a serialization function It is helpful to have an object serialization function tailored to the structure of an object (as defined by its class) such that the result of serializing an object is a humanreadable string representation of the object showing all relevant information items of it. By convention, these functions are called toString(). In the case of the Book class, we use the following code: Book.prototype.toString = function () { return "Book{ ISBN:" + this.isbn + ", title:" + this.title + ", year:" + this.year + (this.edition || "") +"}"; };

144

8 Implementing Constraint Validation in a Plain JS Web App

8.5.6 Data management operations In addition to defining the model class in the form of a constructor function with property definitions, checks and setters, as well as a toString() serialization function, we also need to define the following data management operations as class-level methods of the model class: 1. Book.convertRec2Obj and Book.retrieveAll for loading all managed Book instances from the persistent data store. 2. Book.saveAll for saving all managed Book instances to the persistent data store. 3. Book.add for creating a new Book instance and adding it to the collection of all Book instances. 4. Book.update for updating an existing Book instance. 5. Book.destroy for deleting a Book instance. 6. Book.createTestData for creating a few sample book records to be used as test data. 7. Book.clearData for clearing the book data store. All of these methods essentially have the same code as in our minimal app discussed in Part 1, except that now 1. we may have to catch constraint violations in suitable try-catch blocks in the procedures Book.convertRec2Obj, Book.add, Book.update and Book. createTestData; 2. we create more informative status and error log messages for better observing what’s going on; and 3. we can use the toString() function for serializing an object in status and error messages. Notice that for the change operations add (create) and update, we need to implement an all-or-nothing policy: whenever there is a constraint violation for a property, no new object must be created and no (partial) update of the affected object must be performed. When a constraint violation is detected in one of the setters called when new Book(…) is invoked in Book.add, the object creation attempt fails, and instead a constraint violation error message is created. Otherwise, the new book object is added to Book.instances and a status message is created, as shown in the following program listing: Book.add = function (slots) { var book = null; try { book = new Book( slots); } catch (e) { console.log( e.constructor.name +": "+ e.message);

8.5 Write the Model Code

145

book = null; } if (book) { Book.instances[book.isbn] = book; console.log( book.toString() + " created!"); } };

When an object of a model class is to be updated, we first create a clone of it for being able to restore it if the update attempt fails. In the object update attempt, we only assign those properties of the object the value of which has changed, and we report this in a status log. Normally, all properties defined by a model class, except the standard identifier attribute, can be updated. It is, however, possible to also allow updating the standard identifier attribute. This requires special care for making sure that all references to the given object via its old standard identifier are updated as well. When a constraint violation is detected in one of the setters invoked in Book. update, the object update attempt fails, and instead the error message of the constraint violation object thrown by the setter and caught in the update method is shown, and the previous state of the object is restored. Otherwise, a status message is created, as shown in the following program listing: Book.update = function (slots) { var book = Book.instances[slots.isbn], noConstraintViolated = true, updatedProperties = [], objectBeforeUpdate = util.cloneObject( book); try { if (book.title !== slots.title) { book.setTitle( slots.title); updatedProperties.push("title"); } if (book.year !== parseInt( slots.year)) { book.setYear( slots.year); updatedProperties.push("year"); } if (slots.edition && slots.edition !== book.edition) { // slots.edition has a non-empty value that is new book.setEdition( slots.edition); updatedProperties.push("edition"); } else if (!slots.edition && book.edition !== undefined) { // slots.edition has an empty value that is new delete book.edition; updatedProperties.push("edition"); } } catch (e) {…} … };

146

8 Implementing Constraint Validation in a Plain JS Web App

Notice that optional properties, like edition, need to be treated in a special way. If the user doesn’t enter any value for them in a Create or Update user interface, the form field’s value is the empty string "". In the case of an optional property, this means that the property is not assigned a value in the add use case, or that it is unset if it has had a value in the update use case. This is different from the case of a mandatory property, where the empty string value obtained from an empty form field may or may not be an admissible value. If there is a constraint violation exception, an error message is written to the log and the object concerned is reset to its previous state: Book.update = function (slots) { … try { … } catch (e) { console.log( e.constructor.name +": "+ e.message); noConstraintViolated = false; // restore object to its state before updating Book.instances[slots.isbn] = objectBeforeUpdate; } if (noConstraintViolated) { if (updatedProperties.length > 0) { console.log("Properties " + updatedProperties.toString() + " modified for book " + slots.isbn); } else { console.log("No property value changed for book " + slots.isbn + " !"); } } };

8.6 Write the View Code The user interface (UI) consists of a start page index.html that allows the user choosing one of the data management operations by navigating to the corresponding UI page such as retrieveAndListAllBooks.html or createBook.html in the app folder. The start page index.html has been discussed in Section 4.2. We render the data management menu items in the form of buttons. For simplicity, we invoke the Book.clearData() and Book.createTestData() methods directly from the buttons’ onclick event handler attribute. Notice, however, that it is generally preferable to register such event handling functions with addEventListener(…), as we do in all other cases.

8.6 Write the View Code

147

8.6.1 The data management UI pages Each data management UI page loads the same basic CSS and JavaScript files like the start page index.html discussed above. In addition, it loads a use-case-specific view code file src/v/useCase.js and then sets the setupUserInterface procedure of the use-case as an event handler for the page load event, which takes care of initializing the use case when the UI page has been loaded.

8.6.2 Initialize the app For initializing the app, its namespace and MVC sub-namespaces have to be defined. For our example app, the main namespace is defined to be pl, standing for “Public Library”, with the three sub-namespaces m, v and c being initially empty objects: var pl = { m:{}, v:{}, c:{} };

We put this code in the file initialize.js in the c folder.

8.6.3 Set up the user interface For setting up the user interfaces of the data management use cases, we have to distinguish the case of “Retrieve/List All” from the other ones (Create, Update, Delete). While the latter ones require using an HTML form and attaching event handlers to form controls, in the case of “Retrieve/List All” we only have to render a table displaying all books, as in the case of the Minimal App³ discussed in Chapter 3. For the Create, Update and Delete use cases, we need to add event listeners for: 1. responsive validation on form field input events, 2. handling the event when the user clicks (or pushes) the save (or delete) button, 3. making sure the main memory data is saved when a beforeunload event occurs, that is, when the browser window/tab is closed. For the use case Create, we obtain the following code (in v/createBook.js):: pl.v.createBook = { setupUserInterface: function () { var formEl = document.forms['Book'], saveButton = formEl.commit; // load all book records Book.retrieveAll(); // add event listeners for responsive validation formEl.isbn.addEventListener("input", function () {

 http://web-engineering.info/tech/JsFrontendApp/MinimalApp-with-CSS/index.html

148

8 Implementing Constraint Validation in a Plain JS Web App

formEl.isbn.setCustomValidity( Book.checkIsbnAsId( formEl.isbn.value).message); }); formEl.title.addEventListener("input", function () { formEl.title.setCustomValidity( Book.checkTitle( formEl.title.value).message); }); formEl.year.addEventListener("input", function () { formEl.year.setCustomValidity( Book.checkYear( formEl.year.value).message); }); formEl.edition.addEventListener("input", function () { formEl.edition.setCustomValidity( Book.checkEdition( formEl.edition.value).message); }); … } };

Notice that for each input field we add a listener for input events, such that on any user input a validation check is performed because input events are created by user input actions such as typing. We use the predefined function setCustomValidity from the HTML5 form validation API for having our property check functions invoked on the current value of the form field and returning an error message in the case of a constraint violation. So, whenever the string represented by the expression Book. checkIsbn( formEl.isbn.value).message is empty, everything is fine. Otherwise, if it represents an error message, the browser indicates the constraint violation to the user by rendering a red outline for the form field concerned (due to our CSS rule for the :invalid pseudo class). In addition to the event handlers for responsive constraint validation, we need two more event handlers: pl.v.createBook = { setupUserInterface: function () { … // Set an event handler for the submit/save button saveButton.addEventListener("click", pl.v.createBook.handleSaveButtonClickEvent); // neutralize the submit event formEl.addEventListener( 'submit', function (e) { e.preventDefault(); formEl.reset(); }); // when the browser window/tab is closed window.addEventListener("beforeunload", Book.saveAll); }, handleSaveButtonClickEvent: function () {…} };

8.6 Write the View Code

149

While the validation on user input enhances the usability of the UI by providing immediate feedback to the user, validation on form data submission is even more important for catching invalid data. Therefore, the event handler handleSaveButton ClickEvent() performs the property checks again with the help of setCustomValidity, as shown in the following program listing: handleSaveButtonClickEvent: function () { var formEl = document.forms['Book']; var slots = {isbn: formEl.isbn.value, title: formEl.title.value, year: formEl.year.value}; // set error messages in case of constraint violations formEl.isbn.setCustomValidity( Book.checkIsbnAsId( slots.isbn).message); formEl.title.setCustomValidity( Book.checkTitle( slots.title).message); formEl.year.setCustomValidity( Book.checkYear( slots.year).message); if (formEl.edition.value) { slots.edition = formEl.edition.value; formEl.edition.setCustomValidity( Book.checkEdition( slots.edition).message); } // save the input data only if all input fields are valid if (formEl.checkValidity()) Book.add( slots); }

By invoking checkValidity() on the form element, we make sure that the form data is only saved (by Book.add), if there is no constraint violation. After this handleSaveButtonClickEvent handler has been executed on an invalid form, the browser takes control and tests if the predefined property validity has an error flag for any form field. In our approach, since we use setCustomValidity, the validity.customError would be true. If this is the case, the custom constraint violation message will be displayed (in a bubble) and the submit event will be suppressed. In the UI of the use case Update, which is handled in v/updateBook.js, we do not have an input, but rather an output field for the standard identifier attribute isbn, since it is not supposed to be modifiable. Consequently, we don’t need to validate any user input for it. However, we need to set up a selection list (in the form of an HTML select element) allowing the user to select a learning unit in the first step, before its data can be modified. This requires to add a change event listener on the select element such that the fields of the UI can be filled with the data of the selected object. pl.v.updateBook = { setupUserInterface: function () { var formEl = document.forms['Book'],

150

8 Implementing Constraint Validation in a Plain JS Web App

submitButton = formEl.commit, selectBookEl = formEl.selectBook; // set up the book selection list util.fillSelectWithOptions( Book.instances, selectBookEl, "isbn", "title"); // when a book is selected, fill the form with its data selectBookEl.addEventListener("change", function () { var book=null, bookKey = selectBookEl.value; if (bookKey) { // set form fields and reset CustomValidity book = Book.instances[bookKey]; ["isbn","title","year","edition"].forEach( function (p) { formEl[p].value = book[p] !== undefined ? book[p] : ""; formEl[p].setCustomValidity(""); // no error }); } else formEl.reset(); }); // add event listeners for responsive validation … // Set an event handler for the submit/save button … // neutralize the submit event … // Set a handler for the event when the browser window/tab is closed … }, handleSaveButtonClickEvent: function () {…} };

There is no need to set up responsive validation for the standard identifier attribute isbn, but for all other form fields, as shown above for the Create use case. The logic of the setupUserInterface method for the Delete use case is similar. We only need to take care that the object to be deleted can be selected by providing a selection list, like in the Update use case. No validation is needed for the Delete use case.

8.7 Run the App and Get the Code You can run the validation app⁴ from our server or download the code⁵ as a ZIP archive file.

 http://web-engineering.info/tech/JsFrontendApp/ValidationApp/index.html  http://web-engineering.info/tech/JsFrontendApp/ValidationApp.zip

8.8 Possible Variations and Extensions

151

8.8 Possible Variations and Extensions 8.8.1 Adding an object-level validation function When object-level validation (across two or more properties) is required for a model class, we can add a custom validation function validate to it, such that objectlevel validation can be performed before save by invoking validate on the object concerned. For instance, for expressing the constraint defined in the class model shown in Figure 7.1, we define the following validation function: Author.prototype.validate = function () { if (this.dateOfDeath && this.dateOfDeath < this.dateOfBirth) { throw new ConstraintViolation( "The dateOfDeath must be after the dateOfBirth!"); } };

When a validate function has been defined for a model class, it can be invoked in the create and update methods. For instance, Author.add = function (slots) { var author = null; try { author = new Author( slots); author.validate(); } catch (e) { console.log( e.constructor.name +": "+ e.message); } };

8.8.2 Using implicit JS setters Since ES5, JavaScript has its own form of setters, which are implicit and allow having the same semantics as explicit setter methods, but with the simple syntax of direct access. In addition to having the advantage of a simpler syntax, implicit JS setters are also safer than explicit setters because they decrease the likelihood of a programmer circumventing a setter by using a direct property assignment when instead a setter should be used. In other OOP languages, like Java, this is prevented by declaring properties to be ’private’. But JavaScript does not have this option. The following code defines implicit setter and getter methods for the property title: Object.defineProperty( Book.prototype, "title", { set: function(t) { var validationResult = Book.checkTitle( t);

152

8 Implementing Constraint Validation in a Plain JS Web App

if (validationResult instanceof NoConstraintViolation) { this._title = t; } else { throw validationResult; } }, get: function() { return this._title; } });

Notice that, also in the constructor definition, the internal property _title, used for storing the property value, is not used for setting/getting it, but rather the virtual property title: Book = function (slots) { this.learnUnitNo = 0; this.title = ""; if (arguments.length > 0) { this.learnUnitNo = slots.learnUnitNo; this.title = slots.title; // optional property if (slots.subjectArea) this.subjectArea = slots.subjectArea; } });

We will start using implicit setter and getter methods, along with ES6 class definitions, in Chapter 11.

8.9 Points of Attention 8.9.1 Boilerplate code An issue with the do-it-yourself code of this example app is the boilerplate code needed 1. per model class for the storage management methods add, update, destroy, etc.; 2. per model class and property for getters, setters and validation checks. While it is good to write this code a few times for learning app development, you don’t want to write it again and again later when you work on real projects. In Volume 2, we present an approach how to put these methods in a generic form in a meta-class, such that they can be reused in all model classes of an app.

8.10 Practice Projects

153

8.9.2 Configuring the UI for preventing invalid user input Some of the new HTML5 input field types (like number, date or color) are intended to allow web browsers rendering corresponding input elements in the form of UI widgets (like date or color pickers) that limit the user’s input options such that only valid input is possible. In terms of usability, it’s preferable to prevent users from entering invalid data instead of allowing to enter it and only then checking its validity and reporting errors. Unfortunately, and this is quite disappointing, many browsers do, in 2017, still not have reasonable widget implementations for these HTML5 input field types yet.

8.10 Practice Projects For the following projects, you have to take care of 1. adding, for every property, a check function that validates the constraints defined for the property, and a setter method that invokes the check function and is to be used for setting the value of the property, 2. performing validation before any data is saved in the add and update methods. in the model code of your app, while In the user interface (“view”) code you have to take care of 1. styling the user interface with CSS rules (for instance, by integrating a CSS library such as Yahoo’s Pure CSS), 2. validation on user input for providing immediate feedback to the user, 3. validation on form submission for preventing the submission of invalid data. Make sure that your pages comply with the XML syntax of HTML5 by means of XHTML5 validation⁶ (setting the validator field Preset to “HTML5 + SVG 1.1 + MathML 3.0”), and that your JavaScript code complies with our Coding Guidelines⁷ and its style is checked with JSHint⁸. If you have any questions about how to carry out the following projects, you can ask them on our discussion forum⁹.

8.10.1 Project 1 – Validate movie data The purpose of the app to be built is managing information about movies. Like in the book data management app discussed in the tutorial, you can make the simplifying    

https://validator.nu/ http://oxygen.informatik.tu-cottbus.de/webeng/Coding-Guidelines.html http://jshint.com/ http://web-engineering.info/forum/12

154

8 Implementing Constraint Validation in a Plain JS Web App

assumption that all the data can be kept in main memory. Persistent data storage is implemented with JavaScript’s Local Storage API. The app deals with just one object type: Movie, as depicted in the following class diagram.

In this model, the following constraints have been expressed: 1. Due to the fact that the movieId attribute is declared to be the standard identifier of Movie, it is mandatory and unique. 2. The title attribute is mandatory, as indicated by its multiplicity expression [1], and has a string length constraint requiring its values to have at most 120 characters. 3. The releaseDate attribute has an interval constraint: it must be greater than or equal to 1895 – 12 – 28. Notice that the releaseDate attribute is not mandatory, but optional, as indicated by its multiplicity expression [0..1]. In addition to the constraints described in this list, there are the implicit range constraints defined by assigning the datatype PositiveInteger to movieId, NonEmptyString to title, and Date to releaseDate. In our plain JavaScript approach, all these property constraints are coded in the model class within property-specific check functions. You can use the following sample data for testing your app: Table 8.2 Sample data about movies Movie ID

Title

Release date

   

Pulp Fiction Star Wars Casablanca The Godfather

 –  –   –  –   –  – 

8.10 Practice Projects

155

More movie data can be found on the IMDb website¹⁰.

8.10.2 Project 2 – Validate country data The purpose of the app to be built is managing information about countries. The app deals with just one object type: Country, as depicted in the following class diagram.

In this model, the following constraints have been expressed: 1. Due to the fact that the name attribute is declared to be the standard identifier of Country, it is mandatory and unique. 2. The name attribute has a string length constraint requiring its values to have at least 3 and at most 50 characters. 3. The population attribute is mandatory, as indicated by the multiplicity expression [1] appended to the attribute name. 4. The lifeExpectancy attribute is also mandatory and has an interval constraint: its values must be less than or equal to 100. Notice that the militaryExpenditure attribute is not mandatory, but optional, as indicated by its multiplicity expression [0..1]. In addition to the constraints described in this list, there are the implicit range constraints defined by assigning the datatypes NonEmptyString to name, PositiveInteger to population, PositiveDecimal to lifeExpectancy and Percentage to militaryExpenditure (hint: a percentage value is a decimal number between 0 and 100). In our plain JavaScript approach, all these property constraints are coded in the model class within property-specific check functions. You can use the sample data shown in the following table for testing your app.

 http://www.imdb.com

156

8 Implementing Constraint Validation in a Plain JS Web App

Table 8.3 Sample data about countries Name

Population

Life expectancy

Military expend. (% GDP)

Germany France Russia Monaco

,, ,, ,, ,

. . . .

. . .

More data about countries can be found in the CIA World Factbook¹¹.

8.11 Quiz Questions If you would like to look up the answers for the following quiz questions, you can check our discussion forum¹². If you don’t find an answer in the forum, you may create a post asking for an answer to a particular question.

8.11.1 Question 1: Validation in setter (1) Complete the following setter code fragment: Book.prototype.setIsbn = function (isbn) { var validationResult = ______________________________; if (validationResult instanceof NoConstraintViolation) { this.isbn = isbn; } else { … ; } };

8.11.2 Question 2: Validation in setter (2) Complete the following setter code fragment: Book.prototype.setIsbn = function (isbn) { var validationResult = …; if (validationResult instanceof NoConstraintViolation) { this.isbn = isbn; } else {

 https://www.cia.gov/library/publications/the-world-factbook/  http://web-engineering.info/forum/12

8.11 Quiz Questions

157

__________________________; } };

8.11.3 Question 3: Methods to add in JS class model

Consider the simple information design model shown in the class diagram. Which of the following methods have to be added to the Publisher class in a corresponding JavaScript class model? Select one or many: ☐ checkName( n: String): ConstraintViolation ☐ getName(): String ☐ setName( n: String) ☐ checkNameAsId( n: String): ConstraintViolation ☐ checkNameAsId( n: String): ConstraintViolation ☐ checkName( n: String): ConstraintViolation ☐ setName( n: String) Notice that an underlined method name denotes a class-level (“static”) method.

8.11.4 Question 4: Implementing constraints

Consider the constraints specified for the object type Person in the class diagram. Which of the following JavaScript code fragments implements these constraints? Select one: 1. ○ if (name === undefined) { return "A name is required!"; } else if (typeof name !== "string" || name.trim() === "") { return "Name must be a non-empty string!"; } else if (age !== undefined) { if (!Number.isInteger( age) || age < 0) { return "Age must be a non-negative integer!" } } else return "";

// no error

158

2.

8 Implementing Constraint Validation in a Plain JS Web App

○ if (name === undefined) { return "A name is required!"; } else if (typeof name !== "string") { return "Name must be a string!"; } else if (age !== undefined) { if (!Number.isInteger( age) || age < 0) { return "Age must be a non-negative integer!" } } else return "";

3.

// no error

○ if (name === undefined) { return "A name is required!"; } else if (typeof name !== "string" || name.trim() === "") { return "Name must be a non-empty string!"; } else if (age < 0) { return "Age must be a non-negative integer!" } else return "";

4.

// no error

○ if (name === undefined) { return "A name is required!"; } else if (typeof name !== "string" || name.trim() === "") { return "Name must be a non-empty string!"; } else if (age === undefined || !Number.isInteger( age) || age < 0) { return "Age must be a non-negative integer!" } else return "";

// no error

9 Implementing Constraint Validation in a Java EE Web App The minimal web app that we have discussed in Part 1 has been limited to support the minimum functionality of a data management app only. For instance, it did not take care of preventing the user from entering invalid data into the app’s database. In this chapter, we show how to express integrity constraints in a Java EE entity class, and how to have constraints automatically validated on critical life cycle events of entity objects with JPA, and on form submission with JSF.

9.1 Java Annotations for Persistent Data Management and Constraint Validation The integrity constraints of a distributed app have to be checked both in model classes and in the underlying database, and possibly also in the UI. However, this requirement for three-fold validation should not imply having to define the same constraints three times in three different languages: in Java, in SQL and in HTML5/JavaScript. Rather, the preferred approach is to define the constraints only once, in the model classes, and then reuse these constraint definitions also in the underlying database and in the UI. Java EE apps support this goal to some degree. There are two types of constraint annotations: 1. JPA constraint annotations, specify constraints to be used for generating the database schema (with CREATE TABLE statements) such that they are then checked by the DBMS, and not by the Java runtime environment; 2. Bean Validation annotations specify constraints to be checked by the Java runtime environment In this section we discuss how to use some of the predefined constraint annotations and how to define a custom constraint annotation for the year property of the Book class, since its value has an upper bound defined by an expression (’next year’).

9.1.1 JPA constraint annotations The JPA constraint annotations specify constraints to be used by the underlying database management system after generating the database schema, but not for Java validation. Consider the @Id annotation in the following definition of an entity class Item:

https://doi.org/10.1515/9783110499957-009

160

9 Implementing Constraint Validation in a Java EE Web App

@Entity @Table( name="items") public class Item { @Id private String itemCode; private int quantity; … // define constructors, setters and getters }

The @Id annotation of the itemCode attribute is mapped to a SQL primary key declaration for this attribute in the corresponding database table schema. As a consequence, the itemCode column of the generated items table must have a value in each row and these values have to be unique. However, these conditions are not checked in the Java runtime environment. JPA generates the following CREATE TABLE statement: CREATE TABLE IF NOT EXISTS items ( itemCode varchar(255) NOT NULL PRIMARY KEY, quantity int(11) DEFAULT NULL )

Since nothing has been specified about the length of itemCode strings, the length is set to 255 by default. However, in our case we know that itemCode has a fixed length of 10, which can be enforced by using the @Column annotation, which has the following parameters: – name allows to specify a name for the column to be used when the table is created (by default, the attribute name of the entity class is used); – nullable is a boolean parameter that defines if the column allows NULL values (by default, it is true); – length is a positive integer, specifying the maximum number of characters allowed for string values of that column (by default, this is 255); – unique is a boolean parameter that defines if the values of the column must be unique (by default, it is false). Using the @Column annotation, the improved Java/JPA code of the model class is: @Entity @Table( name="items") public class Item { @Id @Column( length=10) private String itemCode; @Column( nullable=false) private int quantity; … // define constructors, setters and getters }

As a result, the generated CREATE TABLE statement now contains the additional constraints expressed for the columns itemCode and quantity:

9.1 Java Annotations for Persistent Data Management and Constraint Validation

161

CREATE TABLE IF NOT EXISTS items ( itemCode varchar(10) NOT NULL PRIMARY KEY, quantity int(11) NOT NULL )

9.1.2 Bean Validation annotations In the Java EE Bean Validation¹ approach, Java runtime validation can be defined in the form of bean validation annotations placed on a property, method, or class. Table 9.1 Bean Validation annotations for properties Constraint Type

Annotations

Examples

String Length Constraints

@Size

@Size( min=8, max=80) String message;

Cardinality Constraints (for arrays, @Size collections and maps)

@Size( min=2, max=3) List coChairs;

Mandatory Value Constraints

@NotNull

@NotNull String name

Range Constraints for numeric attributes

@Digits

@Digits( integer=6, fraction= 2) BigDecimal price;

Interval Constraints for integervalued attributes

@Min and @Max

@Min(5) int teamSize

Interval Constraints for decimalvalued attributes

@DecimalMin and @DecimalMax

@DecimalMax("30.00") double voltage

Pattern Constraints

@Pattern

@Pattern( regexp="\\b\\d{10}\ \b") String isbn;

In addition, there are annotations that require a date value to be in the future (@Future) or in the past (@Past). All Bean Validation annotations have an optional message attribute for defining a custom error message. In the following example, we add two @NotNull annotations with messages, a @Size and a @Min annotation to the JPA constraint annotations. The @NotNull annotations constrain the itemCode and the quantity attributes to be mandatory, while the @Min annotation constrains the quantity attribute to have a minimum value of 0: @Entity @Table( name="items") public class Item { @Id @Column( length=8) @NotNull( message="An item code is required!")

 http://docs.oracle.com/javaee/7/tutorial/doc/bean-validation001.htm#GIRCZ

162

9 Implementing Constraint Validation in a Java EE Web App

@Size( min=8, max=8) private String itemCode; @Column( nullable=false) @NotNull( message="A quantity is required!") @Min(0) private int quantity; }

Notice that that we need some duplicate logic in this example because the same constraints may have to be defined twice: as a JPA constraint and as a Bean Validation constraint. For instance, for a mandatory attribute like quantity we have both a @Column( nullable=false) JPA constraint annotation and a @NotNull Bean Validation annotation.

9.2 New Issues Compared to the Minimal App² discussed in Chapter 4 we have to deal with a number of new issues: 1. In the model layer we have to take care of adding for every property the constraints that must be checked before allowing a record to be saved to the database 2. In the user interface (view) we have to take care of form validation providing feedback to the user whenever data entered in the form is not valid. Checking the constraints in the user interface on user input is important for providing immediate feedback to the user. Using JSF and Bean Validation requires to submit the form before the validation checks are performed. It would be preferable to define the validation checks in the model classes only and use them in the user interface before form submission, without having to duplicate the validation logic in the JSF facelets. However, at this point in time, JSF does not support this, and the validation is performed only after the form is submitted. Using HTML5 validation attributes in the JSF facelets to enforce HTML5 validation before submitting the form requires an undesirable duplication of validation logic. The effect of such a duplication would be duplicate maintenance of the validation code, once in the model classes and once more in the user interface. In a simple application like our example app, this is doable, but in a larger application this quickly becomes a maintenance nightmare.

 http://web-engineering.info/tech/JavaJpaJsfApp/MinimalApp/index.html

9.3 Make an Entity Class Model

163

9.3 Make an Entity Class Model Using the information design model shown in Figure 7.2 above as the starting point, we make an Entity class model with getters/setters and corresponding Java datatypes.

Figure 9.1 Deriving an Entity class model from an information design model

The Entity class model shown on the right hand side in Figure 9.1 defines getters and setters for all properties and the following property constraint annotations: 1. Using @Id and @NotNull, the isbn attribute is declared to be a standard identifier, implying that it is mandatory and unique. 2. Using @Pattern(“\\b\\d{10}\\b”), the isbn attribute has a pattern constraint requiring its values to match the ISBN-10 format (simplified to the case of 10digit strings). 3. Using @NotNull and @Size( max=50), the title attribute is mandatory and has a string length maximum constraint of at most 50 characters. 4. Using @NotNull, @Min( 1459) and the custom annotation @UpToNextYear, the year attribute is mandatory and has an interval constraint, of a special form where the minimum is 1459 and the maximum is not fixed, but provided by a custom annotation implementing the calendar arithmetic function nextYear(). Since there is no predefined Bean Validation annotation for checking the uniqueness of an ID value provided when creating a new entity object, we define a static method checkIsbnAsId that can be invoked in a corresponding controller method when creating a new entity object. In addition, the entity class model defines the static CRUD data management methods retrieveAll, create, update and delete.

164

9 Implementing Constraint Validation in a Java EE Web App

9.4 Write the Model Code The Entity class model shown on the right hand side in Figure 9.1 can be coded step by step for getting the code of the entity classes of our Java EE web app.

9.4.1 Type mapping When defining the properties, we first need to map the platform-independent datatypes of the information design model to the corresponding implicit Java supported datatypes according to the following table. Table 9.2 Datatype mapping to Java Platform-independent datatype

Java datatype

String Integer Decimal Boolean Date

String int, long, Integer, Long double, Double, java.math.BigDecimal boolean, Boolean java.util.Date

Notice that for precise computations with decimal numbers, the special datatype java.math.BigDecimal³ is needed. A second datatype mapping is needed for obtaining the corresponding MySQL datatypes: Table 9.3 Datatype mapping to MySQL Platform-independent datatype

MySQL datatype

String Integer Decimal Boolean Date

VARCHAR INT DECIMAL BOOL DATETIME or TIMESTAMP

9.4.2 Code the constraints as annotations In this section we add JPA constraint annotations and Bean Validation annotations for implementing the property constraints defined for the Book class in the Java En http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial

9.4 Write the Model Code

165

tity class model. For the standard identifier attribute isbn, we add the JPA constraint annotations @Id and @Column( length=10), as well as the Bean Validation annotations @NotNull and @Pattern( regexp="\\b\\d{10}\\b"). Notice that, for readability, we have simplified the ISBN pattern constraint. For the attribute title, we add the JPA constraint annotation @Column( nullable=false), as well as the Bean Validation annotations @NotNull and @Size( max=50). For the attribute year, we add the JPA constraint annotation @Column( nullable=false), as well as the Bean Validation annotations @NotNull and @Min( value=1459). Notice that we cannot express the constraint that year must not be greater than next year with a standard validation annotation. Therefore, we’ll define a custom annotation for this constraint in Section 6 below. Coding the integrity constraints with JPA constraint annotations and Bean Validation annotations results in the following annotated bean class: @Entity @Table( name="books") @ManagedBean( name="book") @ViewScoped public class Book { @Id @Column( length=10) @NotNull( message="An ISBN value is required!") @Pattern( regexp="\\b\\d{10}\\b", message="The ISBN must be a 10-digit string!") private String isbn; @Column( nullable=false) @NotNull( message="A title is required!") @Size( max=255) private String title; @Column( nullable=false) @NotNull( message="A year is required!") @Min( value=1459, message="The year must not be before 1459!") private Integer year; …

// define constructors, setters and getters

public public public public public

static static static static static

Book getObjectByStdId(…) {…} List getAllObjects(…) {…} void create(…) throws Exception {…} void update(…) throws Exception {…} void delete(…) throws Exception {…}

}

Notice that for the year property, the Java Integer wrapper class is used instead of the primitive int datatype. This is required for the combined use of JSF and JPA, because if the value of an empty year input field is submitted in the create or update forms, the value which is passed to the year property by JSF via the setYear method is null (more details on Section 4.5, “Requiring non-empty strings”), which is not admitted for primitive datatypes by Java.

166

9 Implementing Constraint Validation in a Java EE Web App

We only provide an overview of the methods. For more details, see Chapter 4.

9.4.3 Checking uniqueness constraints For avoiding duplicate Book records we have to check that the isbn values are unique. At the level of the database, this is already checked since the isbn column is the primary key, and the DBMS makes sure that its values are unique. However, we would like to check this in our Java app before the data is passed to the DBMS. Unfortunately, there is no predefined Bean Validation annotation for this purpose, and it is not clear how to do this with a custom validation annotation. Therefore we need to write a static method, Book.checkIsbnAsId, for checking if a value for the isbn attribute is unique. This check method can then be called by the controller for validating any isbn attribute value before trying to create a new Book record. The Book.checkIsbnAsId method code is shown below: public static void checkIsbnAsId( EntityManager em, String isbn) throws UniquenessConstraintViolation, MandatoryValueConstraintViolation { if (isbn == null) { throw new MandatoryValueConstraintViolation( "An ISBN value is required!"); } else { Book book = Book.retrieve( em, isbn); // book was found, uniqueness constraint validation failed if ( book != null) { throw new UniquenessConstraintViolation( "There is already a book record with this ISBN!"); } } }

The method throws a UniquenessConstraintViolation exception in case that a Book record was found for the given ISBN value. The exception can then be caught and a corresponding error message displayed in the UI. In the sequel of this chapter we show how to define the controller validation method and inform JSF facelets that it must be used to validate the isbn form input field. Notice that in this case we also need to check the isbn value and reject null values, because the @NotNull validation triggers only later, when the isbn property of the Book is set, thus at this point we could get NullPointerException, from the Book.retrieve method.

9.4 Write the Model Code

167

9.4.4 Dealing with model-related exceptions The Book.checkIsbnAsId method discussed in the previous sub-section is designed to be used in combination with a controller so the user gets an error message when trying to duplicate a Book record (i. e., if the provided isbn value is already used in an existing record). However, if the Book.create method is used directly (i. e. by another piece of code, where the uniqueness constraint is not performed by calling Book.checkIsbnAsId), then uniqueness constraint validation may fail. Lets have a look on the Book.create code: public static void create( EntityManager em, UserTransaction ut, String isbn, String title, int year) throws NotSupportedException, SystemException, IllegalStateException, SecurityException, HeuristicMixedException, HeuristicRollbackException, RollbackException, EntityExistsException { ut.begin(); Book book = new Book( isbn, title, year); em.persist( book); ut.commit(); }

The method may throw a number of exceptions when trying to run the persist or the commit method. One of the exceptions (i. e. EntityExistsException) is thrown by the ut.commit call. The method which calls Book.create may catch this exception and perform specific actions, such as rolling back the transaction. In our case, the Book.create is called by the create action method of the BookController class, and the action performed is to show the exception stack trace in the console, as well as calling the ut.rollback which takes care of cancelling any database change performed by the current transaction. The rest of the exceptions are caught by using their super class (i. e. Exception) and the exception stack trace is displayed in the console. public String create( String isbn, String title, int year) { try { Book.create( em, ut, isbn, title, year); } catch ( EntityExistsException e) { try { ut.rollback(); } catch ( Exception e1) { e1.printStackTrace(); } e.printStackTrace(); } catch ( Exception e) { e.printStackTrace(); } return "create"; }

168

9 Implementing Constraint Validation in a Java EE Web App

Note: the EntityExistsException is part of the javax.persistence package (i. e. javax.persistence.EntityExistsException). TomEE uses the Apache OpenJPA⁴ implementation of the JPA API, which means that the EntityExistsException class (and other exceptions classes too) are part of the org. apache.openjpa.persistence package. Therefore, using this exception with our code, requires to import org.apache.openjpa.persistence.EntityExistsException instead of import javax.persistence.EntityExistsException as well as adding the openjpa-xxx.jar (located in the lib subfolder of the TomEE installation folder) to the Java application class path for being able to have the code compiled with Eclipse or other IDE tools.

9.4.5 Requiring non-empty strings Normally a mandatory string-valued attribute, such as title, requires a non-empty string, which is expressed in our model above by the range NonEmptyString. For treating empty strings as no value, the context parameter javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL must be set to true in web.xml:

javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL

true

9.5 Write the View Code After we have defined the constraints in the Java EE model layer and the database layer, we need to take care of validation in the user interface. In particular, we need to make sure that the user gets informed about issues by rendering visual indicators and informative validation error messages.

9.5.1 Validation in the Create use case The WebContent/views/books/create.xhtml file contains the JSF facelet code for creating a new Book record. We now use the JSF validator attribute for performing the uniqueness validation and JSF message elements for displaying validation error messages.  http://openjpa.apache.org/

9.5 Write the View Code

169

Create a new book record









…



There are only a few changes compared to the same view used for the minimal app, where no validation was performed. The first change is the new h:message element which is bound to a specific form element by the for attribute. We create such an element for each of our form input elements. Notice that we don’t have to do anything else for seeing the validation errors for all integrity constraint checks which are performed by using the (built-in and custom) Bean Validation annotations. As soon as a constraint validation fails, the message set by using the message property of the integrity constraint annotation (e. g. @Pattern, @NotNull, etc) is displayed in an HTML span element generated by JSF as a result of using the h:message element. For all the integrity constraints we have used Bean Validation annotations, but for the uniqueness constraint we have used custom code, therefore no error message will be shown for it. In the view code we can see that a new attribute, validator in h:inputText, was used for the isbn input field. It specifies which custom method is used to perform validation of the provided value in this form field. In our case, we use the checkIsbnAsId method defined in the BookController as shown below: public void checkIsbnAsId( FacesContext context, UIComponent component, Object value) throws ValidatorException { String isbn = (String) value; try { Book.checkIsbnAsId( em, isbn);

170

9 Implementing Constraint Validation in a Java EE Web App

} catch ( UniquenessConstraintViolation e) { throw new ValidatorException( new FacesMessage( FacesMessage.SEVERITY_ERROR, e.getMessage(), e.getMessage())); } catch ( MandatoryValueConstraintViolation e) { throw new ValidatorException( new FacesMessage( FacesMessage.SEVERITY_ERROR, e.getMessage(), e.getMessage())); } }

The controller’s check method throws a ValidatorException which is also used to deliver the error message (the third parameter of the ValidatorException constructor) to the corresponding JSF facelet for being displayed in the UI. Methods used as JSF validators must have a specific syntax. The first two parameters of type FacesContext, respectively UIComponent are used by the container to invoke the method with references to the right view component and context, and they can be used in more complex validation methods. The last one, of type Object, represents the value to be validated by the method. This value has to be casted to the expected type (to String, in our example). It is important to know that, if a cast to a non-compatible type is performed, the validation method fails and an exception is thrown.

9.5.2 Validation in the Update use case In the Update use case, the facelet file update.xhtml in WebContent/views/ books was updated so it uses the h:message elements for being able to display validation errors:

Update a book record



…





9.6 Defining a Custom Validation Annotation

171

…



Since we do not allow to change the ISBN of a book, we create an output field for the isbn attribute with the JSF element h:outputText. This implies that no validation is performed. Using an h:outputText element for showing the value of an entity attribute results in an HTML span element. This implies that the HTTP form submission message contains no information about that attribute. If the validation fails, we expect to see the form content together with the error messages. To get the expected result, we need to use the annotation @ViewScoped for the entity class pl.m.Book instead of @RequestScoped, otherwise our bean instance referenced by the book variable is initialized with a new value on every request, implying that the expression #{book. isbn} evaluates to null and the ISBN value is not displayed. The @ViewScoped annotation specifies that the entity bean is alive as long as the associated view is alive, so the ISBN value stored by the book is available during this time and it can be displayed in the view. By contrast, h:inputText elements result in HTML input elements which are part of the form submission content, so the response contains the already existing values because these values are known in this case. This consideration shows that it is important to choose the right bean scope.

9.6 Defining a Custom Validation Annotation One other integrity constraint we have to consider is about the allowed values of the year property, which must be in the interval [1459, nextYear()] where nextYear() is a function invocation expression. We may have the idea to use @Min and @Max to specify the interval constraint, but this is not possible because the @Max annotation (as well as any other annotation) does not allow expressions, but only data literals. So, while we can express the interval’s lower bound with @Min( value=1459), we need another solution for expressing the upper bound. Fortunately, the Bean Validation API allows to define custom validation annotations with custom code performing the constraint checks. This means that we are free to express any kind of validation logic in this way. Creating and using a custom validation annotation requires the following steps: 1. Create the annotation interface UpToNextYear with the following code: @Target( {ElementType.FIELD, ElementType.METHOD}) @Retention( RetentionPolicy.RUNTIME) @Constraint( validatedBy = UpToNextYearImpl.class) public @interface UpToNextYear {

172

2.

9 Implementing Constraint Validation in a Java EE Web App

String message() default "The value of year must be between 1459 and next year!"; Class[] groups() default {}; Class[] groups() default {}; Class