Sample Design Pattern
Subject: Design Patterns

By: David Wachutka

Change History:

Date

Author

Description

12/15/04

David Wachutka

Initial version

References

Sun Javadoc 1.4

 

Design Patterns Index

Development Cookbook - Writing package level javadoc

1.                Pattern Name and Classification

1.1                   Name

Sample Design Pattern

 

1.2                   Classification

Core Concept Design

2.                Intent

This document provides an example of a design pattern to assist developers in creating design patterns integrated with javadoc.

3.                Also Known As

Design Pattern Design Pattern

4.                 Motivation

The development organization does not have well-defined and/or well-maintained design patterns for how to implement common Windchill features.   By using design patterns more explicitly in our development process will have the following benefits:

·         Improve the quality of code by reusing the knowledge and experience of peers

·         Stimulate creativity by allowing people to focus on solving their particular application problem, rather than spending lots of time reinventing the wheel

·         Improve developers’ understanding of a piece of code they want to reuse so they don’t blindly cut and paste it. This will cut down on inappropriate uses of the code and on the propagation of bad code.

Developers will need to develop design patterns in a consistent format to make them most usable for other developers.  The design pattern should also be integrated into javadoc to limit the number of places developers need to go for information. This approach should also help keep the patterns updated and in line with current API documentation, as well as to easily allow links between patterns and regular JavaDoc.

This design pattern should help developers understand the expected content of the design patterns and also show some examples for including images from Rose, and linking into javadoc.

5.                Applicability

This design pattern should be used as a reference for developers who are creating design patterns. This design pattern should also help to answer the following questions:

1.        What content should be included in a design pattern?

2.        How would images be added in a design pattern?

3.        How would one establish links between the design pattern and javadoc?

6.                Structure

This is a section where it might be useful to include an image (such as a Rose diagram).  Here is an example of how to include an image in a design pattern.

To include the image shown above in this page the following steps were taken. (For this example the package is com.ptc.foo.)

1.        Create a directory named "doc-files" in your package directory (if it doesn’t already exist).  The directory must be named “doc-files” ...com\ptc\foo\doc-files. 

2.        Save any images you are including in the design pattern to the doc-files directory ...com\ptc\foo\doc-files\image.gif

3.        Insert the image into the design pattern document using “Insert/Picture/From File”:

a.        Select the image you want to insert from the doc-files directory.

b.       It is essential that you select “Link to File”.  Do not select “Insert” or “Insert and Link”.

c.        Word will automatically shrink the image to fit within the margins, but we do not want that (the image will not display well).  Right-click the picture in Word and select the "Size" tab.  Under "Scale", set the "Height" and "Width" to "100%", and then click "OK".

1.                Participants

The classes and/or objects participating in the design pattern and their responsibilities.  (Not applicable for the sample design pattern)

2.                Collaborations

How the participants collaborate to carry out their responsibilities.  (Not applicable for the sample design pattern)

3.                Consequences

By using this design pattern as a reference, you should be able to more quickly solve the tricky problems of linking to javadoc or adding images to your design pattern. Additionally, this design pattern should help somewhat with the type of content that is expected for each section of the design pattern.  By choosing not to use this design pattern you may find a better way of accomplishing these tasks or you may run into any number of problems trying to complete your design pattern with the desired images and javadoc links.

4.                Implementation

4.1                   Design Pattern Implementation Checklist

 

      1. Create design pattern content
      2. Add necessary links to the design pattern in javadoc, and also links to javadoc from the design pattern
      3. Add a link to your design pattern in the Design Patterns Index file.
      4. Checkin all materials

-          Design Pattern (.doc and .html formats)

-          Any images used in the design pattern

-          Any packages that have changed or were added

-          Design Pattern Index file

-          Package overview javadoc html files

-          Any other .java files where links were added to the javadoc

4.2                   Creating the design pattern

A good way of implementing the design pattern is by using MS Word to create the document.  The document can then be saved as a web page to create the html format.

1) Create a directory named "doc-files" in your package directory (if it doesn’t already exist).  The directory must be named “doc-files”.  (In this example, the package is com.ptc.foo.)

...\com\ptc\foo\doc-files

2) Create your design pattern using MS Word. The document should be saved in the doc-files directory of the package.  The name of the document should describe the functionality the design pattern is supposed to help implement.  (i.e. Container-based Query)

...\com\ptc\foo\doc-files\<designPatternName>.doc

3) Add links to javadoc in your design pattern where appropriate.

                (See section 11.1)

4) Save the <designPatternName>.doc as "<designPatternName>.html" using “File / Save as Web Page...”.

...\com\ptc\foo\doc-files\<designPatternName>.html

5) Checkin all the files:

  1. ...\com\ptc\foo\doc-files\<designPatternName>.html
  2. ...\com\ptc\foo\doc-files\<designPatternName>.doc
  3. ...\com\ptc\foo\doc-files

4.3                   Add Links to your Design Pattern in javadoc

 

A link to your design pattern should be placed in the package summary section of the package where you check in your design patten.  Additional links should be placed in any other relevant packages, classes, or methods. To add links to your design pattern from javadoc do the following:

 

Add a standard html link in the javadoc comments section of the file:

 

<A HREF=”doc-files/<designPatternName>.html”>Windchill Design Patterns: <Design Pattern Name></A>

 

The path to the design pattern is relative to the package where you’re adding the link.  If your design pattern is in the same package as the java class your adding a link to, it should look like the example above. Otherwise the path is relative to the package where the java class is located.

 

Adding a link in a package summary file:

 

Identify the package summary html file (if one exists).  Probably named something like “package.html”.

 

The link should be added in the html file at the bottom of the page, but above the footer.

 

If there is a corresponding “package.doc” file with the html version the package summary was created using MS Word and then the “Save As Web Page” technique.  In this case add a placeholder link in the .doc version and then do another “Save As Web Page”.  You can then search for the place holder you added in the html version and replace it with the proper relative link to the design pattern.

 

Adding a link in a java file:

 

When adding a link to the design pattern in a java file, add the link the javadoc comments section of the file.

 

Example:

 

Here is a comment section of the SavedQuery class.  Add the link to the design pattern as shown below highlighted in red.  Remember the path to the design pattern is relative to the package where you are adding the link.  In the case below the design pattern is located in the doc-files directory of the class where the link is being added.

 

//##begin SavedQuery%3DDD4F4D0258.doc preserve=no

/**

 *

 * <p>

 * Use the <code>newSavedQuery</code> static factory method(s), not the

 * <code>SavedQuery</code> constructor, to construct instances of this class.

 *  Instances must be constructed using the static factory(s), in order

 * to ensure proper initialization of the instance.

 * <p>

 *<A HREF="doc-files/<designPatternName>.html">Windchill Design Patterns: <DesignPatternName></A>

 *<BR>

 * <BR><BR><B>Supported API: </B>false

 * <BR><BR><B>Extendable: </B>false

 *

 * @version   1.0

 **/

//##end SavedQuery%3DDD4F4D0258.doc

4.4                   Add your Design Pattern to Design Patterns Index

 

There is a Design Patterns Index page that lists all the design patterns alphabetically.  There is a link to the design patterns index page from the javadoc overview page.  When you create a new design pattern you should add the design pattern to the index page.

 

The Design Pattern Index file is located at:

 

Windchill\src\wt\enterprise\doc-files\DesignPatternsIndex.html

 

    1. Checkout the design pattern index file
    2. Add a link to your design pattern
    3. Checkin the updated index file

 

 

For organizational purposes the design patterns index file is maintained with the design pattern links shown in alphabetical order based on the name.  Please add the link to your design pattern accordingly.

 

Example of adding a design pattern to the index file:

 

For this example the design pattern is named Saved Query Design Pattern and is located at wt/query/doc-files/savedQueryDesignPattern.html

 

Insert the following line in the Index html file:

<A HREF="../../query/doc-files/ savedQueryDesignPattern.html ">Saved Query Design Pattern</A><br>

<br>

 

*The path to the design pattern in the index file is relative to src/wt/enterprise/doc-files.

 

If your design pattern was Rware Search Design Pattern and was located at com/ptc/windchill/enterprise/search/server/doc-files/rwareSearchDesignPattern.html

 

The link in the index file would now look like this:

 

<A HREF="../../../com/ptc/windchill/enterprise/search/server/doc-files/ rwareSearchDesignPattern.html ">Rware Search Design Pattern</A><br>

<br>

 

5.                Sample Code

5.1                   Linking to javadoc from the design pattern

 

To add a link to the javadoc of a specific class from your design pattern follow these steps:

 

If you are creating the design pattern using MS Word you won’t be able to add a relative link to the design pattern in the word document.  Instead add a temporary placeholder in the document as shown below.

 

<Link to Saved Query Javadoc>

 

Then after you do the “Save As Web Page...” you can search for that placeholder in the html file and replace it with the proper relative link.  In this case it would be something like this.

 

<A HREF=”../../query/SavedQuery.html”>Link to SavedQuery Javadoc</A>

 

(This example assumes the design pattern is in src/wt/enterprise/doc-files)

6.                Known Uses

This design pattern is used by developers to assist in creating design patterns and integrating with javadoc.

7.                Related Patterns

This design pattern is not related to any others.