NAME: The XML Design Pattern Specification AUTHOR: Darrell Ferguson (darrell.ferguson@ottawa.com) Neal Arthorne (narthorn@chat.carleton.ca) PURPOSE: This XML Schema was developed for to standardize the documentation of design patterns. LAST MODIFICATION: DATE: AUTHOR: DESCRIPTION: ******************************************************************** May 1999 Darrell Ferguson Creation of document Feb 2002 Neal Arthorne Converted DTD to XML Schema Content model for all sections of the pattern. Content model for bold and italic. Used in author elements to display either e-mail addresses or URLs. Problem and context can be in any order, and forces follows either context or problem. Problem and context can be followed by optional symptoms and miscSection sections. Used for figures, graphs and tables. Text content is the description of the image. Used for elements with only string content and the common attributes. Used for elements containing generic content and the common attributes. The overall pattern element. A pattern has a certain list of elements which must be present. Although they may be given different titles in various books, the meaning is always the same. These elements are: - title (a name to use as a reference to the pattern) - authors (sometimes a group) - context (the circumstances in which the problem is being solved) - problem (the specific problem to be solved) - forces (considerations that must be taken into account when choosing a solution to the problem) - solution (proposed solution to the problem) A pattern may also contain several optional portions. Some of these are: - symptoms (pre-existing symptoms) - resulting context (situation after pattern is applied ... more problems?, more patterns to apply?) - related patterns (patterns which may be of interest ... other solutions, variations, involved in resulting context) - known uses (concrete illustrations of the application) - sampleCode (helps show how to implement the pattern) - rationale (why the solution is appropriate) - aliases (other names the pattern is known by) - acknowledgments (anyone who contributed) - references (any resources you want to mention) - miscSection (a miscellaneous section to be labelled by the author) Bullets can be used to create a list of generic content. A bullet can only occur within bullets and may contain any generic content. The title of the pattern must be the first element of the pattern. The title element can only contain text (no images, bullets, or any other component). The authors element can contain only author elements (and must contain at least one author) which may contain text along with emails and websites (no images, bullets, or any other component). The author tag must be used in the authors section of the pattern. It may consist of text (the author's name), emails (one or more) and urls (one or more). The context contains the overall circumstances in which the problem has occurred and imposes constraints on the solution. It could be described by an explicit statement or by a situation. The context may also contain in it, individual forces to be considered when designing the solution. These individual forces should be considered an extension of the forces section of the pattern. The context section may occur before or after the problem section. All patterns solve a problem in a context. If the problem did not exist then the notion of designing a pattern becomes ridiculous. The statement of the problem should be separate from the constraints on the system (the context). The problem description may also contain in it, individual forces to be considered when designing the solution. These individual forces should be considered an extension of the forces section of the pattern. The problem section may occur before or after the context section. The forces section shows what considerations are to be accounted for when deciding on a solution to the problem. This section should also show more clearly the ideas behind the development of the pattern. The forces section (not to be mistaken for the force sections contained in the problem section) must occur after at least one of the problem or context sections. A force section (not to be confused with the forces section in a pattern) may contain any generic content. This section contains the proposed solution to the problem. It is critical for this section to be clear to the reader, as it is the climax of the pattern. The solution section must come after the forces section. Just as one should acknowledge the author of a pattern, anyone who contributed to the development of a pattern should be given recognition as well. Exactly who deserves to be in the acknowledgments will be left to the author or editor of the pattern. These will be other names that the presented pattern might be known. The aliases section is an optional section that may appear between the authors section and the problem, context, and forces sections or, after the problem, context and forces sections and before the solution section. The application of the pattern can sometimes be a little confusing if not illustrated. The known uses section gives us a convenient location to place concrete examples that illustrate the use of the pattern. The miscellaneous section is an optional section that may appear where any of the optional sections may appear. It can appear multiple times throughout the document. It is a section that the writer has felt necessary to put into the documentation of the pattern. It should never be assumed that a pattern contains a miscellaneous section and these sections can be ignored by applications such as pattern searchers and pattern verifiers. The label attribute of any miscellaneous section is required and should be used as the title when displaying or processing the section. The miscellaneous subsection will help pattern writers break up their sections but the breaks should be ignored by some applications (i.e. a pattern verifier). The label of a miscellaneous subsection is required. This section covers the justification of why the presented solution is most appropriate solution relating back to the stated problem and the context of the problem. The references section will list any relevant material that was used in writing the pattern. These can published patterns, books, websites, etc. Included in this list are other possible solutions to the problem, variations of the pattern and patterns that relate to the resulting context. As the name implies, this section describes the state after the application of the pattern. One or more patterns can be included as solutions to new problems that arise. Actual code (usually in C++ or Smalltalk) showing an implementation of the pattern. This section will explain any preexisting symptoms that may be seen and signal that the stated problem exists.