The Qwicap API: The 6 Vital Classes

Qwicap's API was designed to minimize a programmer's learning curve. While the public API consists of, at last count, 58 classes and interfaces, almost all of the functionality is accessed through two classes. Those will occasionally expose you to a handful of additional classes. Beyond those, there are a handful of utility classes that may be useful. There should be little, or no, need to deal with the remaining classes.

The 6 Vital Classes

The Two Principal Classes

• Qwicap - Provides the core functionality of the "full-up" system, including the methods that load web pages from disk, send them to clients, and retrieve and verify the input they return, while automatically requesting input corrections from users as necessary. If you are only using Qwicap for its XML engine, you won't use this class at all.

• Results - Qwicap's XML engine locates specific elements within XML markup by performing searches specified by standard CSS2 selector strings. (The searches are initiated using the get(String) method on any subclass of Markup.) A Results object is created to store the results of each search, which are a list of zero or more elements in the XML markup that matched the specified CSS selector(s). The Results class provides methods for performing every supported manipulation of the elements to which it refers, including duplicating them, changing their contents or attributes, deleting them, and performing further CSS selector searches within them and their children. All such operations return a new instance of Results that references the affected/selected elements.

Four More Classes That You Probably Can’t Avoid

• XMLDocument - Loads an XML document from a file, input stream, or URL, and creates an immutable representation of it in memory. If you want to alter the markup's in-memory representation, invoke its getMutable method to obtain a modifiable copy of it (MutableMarkup). If you are using the "full-up" Qwicap system, you may never need to know about the XMLDocument class because you'll usually load the XML/XHTML documents built-into your web application by using the Qwicap.getDocument methods, which also handle caching of the documents for you. But, if you want to bypass the cache, or load a document from a source that isn't a local file and can't be accessed via a URL, you'll probably find XMLDocument helpful.
• XMLString - Allows you to create XML fragments (or entire documents) from String objects, or any object that happens to produce a usable string from its toString method. This solves a lot of little problems including the following: When you use a method like Results.setContent to insert a string into a body of markup, Qwicap automatically HTML-encodes the string, which is not only correct and convenient, but eliminates a lot of potential problems in any web application. (Conversely, methods like Results.getText automatically translate HTML entities back into Unicode characters, so the strings they return can be treated as normal Java strings, and, if reinstered into the markup, will never end-up double-encoded.) However, that automatic HTML-encoding also means that if you are trying to insert some markup represented by a string, you won't get the result you expect. Wrap that string in an XMLString object, and the problem goes away.
• MutableMarkup - Classes like XMLDocument and XMLString are subclasses of the the ImmutableMarkup class, which means that they represent a body of XML markup that cannot be modified. (Therefore they can be safely cached and shared among threads.) Qwicap initially represents all markup in an immutable state. When you need to modify markup, invoke the getMutable method on it, and you'll receive a MutableMarkup instance. Modifications are normally made by using the get method to select one or more elements in the markup based on a CSS2 selector. That will return a Results object that will provide the methods used to modify the selected elements.

• Match - Results objects are collections of Match objects. Each Match instance identifies a specific element in a document that matched a CSS selector pattern, and provides a full suite of methods for manipulating and examining that element. Almost all of those methods are reflected in the Results class, so you won't usually deal with the Match class. However, Match does supply a few unique methods that make sense for individual elements, but not for lists of elements. Those include getType, getParent, and getAncestors which permit you to do things like identifying the type of an element, or establishing its context in the document.

---

Lesser Classes

Four Supporting Classes

• Form - There's no circumstance under which you must use this class, but using it can reduce the number of assumptions about a form's markup that end-up embedded in your form manipulation code, which gives you greater freedom to change that markup in the future, and tends to simplify your code. It also provides some handy utility methods.

• FormDataSet - Contains a complete set of what are often referred to as "form parameters", but which the W3C officially calls a "form data set". In any case, it's the complete set of data sent from a "form" element (or, more specifically, from all of the "controls" within a "form" element) in one of your web pages. Ordinarily, you won't need this class because you'll retrieve the submitted values using the various "get..." methods in the Qwicap class, e.g. getInt, getString, getDouble. However, if you want to do something like walking the complete list of values that were submitted, the FormDataSet is what makes that possible. You can obtain the current form data set by invoking the Qwicap.getFormDataSet method.

  • FormControlValue - Represents all of the values associated with any given control name in a form data set. If you retrieve information directly from a FormDataSet object, it'll be represented by one of these.

• HTMLEntityCodec - Handles translation from Unicode characters to HTML entity references, and vice versa. If you create your own instance of this class, you can configure the translation on a character-by-character basis, but ordinarily you won't need to do so, because Qwicap keeps a reasonably configured instance of this class on-hand to perform encoding and decoding, which it does automatically. Specifically, encoding is automatically performed when you insert material into XML markup, and decoding is automatically peformed when you retrieve material from XML markup. In practice, this generally means that you don't have to worry about encoding and decoding issues, including the possibility of material being double-encoded, or -decoded when material is extracted from markup and then reinserted. The exceptions to the rule of automatic encoding are the classes that are already known to represent markup (in other words, all subclasses of the Markup class) most notably the aforementioned XMLString class. (This is one of the features that prevents unwanted double-encoding from occurring.)

  Note that the Qwicap class provides the convenience methods htmlEncode and htmlDecode for situations where you need to perform entity encoding/decoding independent of the XML templater's automatic behaviors, but you don't want to create your own instance of HTMLEntityCodec.

• QwicapAbandonmentException - You only need to be aware of this class because you'll be catching it when you implement the standard "Prompt Pattern". As long as you stick with that pattern, you don't need to understand this class and how it is used internally.

Two General-Purpose Convenience Classes

• ArrayToString - Conveniently converts arrays and Collections to strings. (In fact, you can pass it any kind of object at all.) It's not very good with multi-dimensional arrays, or Collections of Collections, or any combination of arrays and Collections, but it still comes in handy. It can be especially useful in connection with logging APIs, because it defers the work of creating the string represention until its toString method is invoked, so log messages that are never written-out, never pay the price of string conversion.
• Null - A set of static utility methods that perform common tasks associated with the handling of null values. Use of these methods frequently eliminates the need to break-up the flow of your code with temporary variables and "if" statements.