Class Library: Web Site Deployment Objects

WebSite. A never-instantiated class which provides shared memory to facilitate inter- and intra-applet communication. Includes the indexes applets, webs, and sites.

package earthstones
import java.awt.*;
java.applet.*;
java.util.*;
class declaration public class WebSite extends Object
class variables private static Hashtable applets = null; An indexed list of (int id, Container app) pairs which permits a host applet to register itself with the WebSite class as an entry in its applets index. A client applet can then access this host by obtaining a reference to it using its id.
private static Hashtable webs = null; An indexed list of (Container app, Web aWeb) pairs.
private static Hashtable sites = null; An indexed list of (Container app, Web aWeb) pairs.
The following variables are necessary to manage the asynchronous nature of networked computing in implementing interapplet communication.
Note. The current approach to managing interapplet communication has limited robustness when multiple sessions are implemented on the same Java Virtual Machine. For example, it IS possible to simultaneously run a non-hosting applet such as JSite as well as the client/host applets Footer/Banner. This is what occurs when the Interapplet Communication Demo is run from EarthStones' website. However, no provisions have been made for the case where two different host/client pairs are simultaneously attempting to get registered and communicating with each other. In this case, a more sophisticated implementation of the busyApp flag would be needed. There is a good discussion of precisely this problem in Oaks, S., & Wong, H. Java Threads. Sebastopol CA: O'Reilly & Associates, 1997.
private static boolean wantsHost = false; Set when a client applet requests a host reference by calling applet(id). This flag is used in handling situations where the client may make the request before the host has registered or an applet that does not register as a host needs to avoid waiting for host.
private static boolean hasHost = false; Set whenever webs is non-empty and checked by web() to allow extra time before attempting to return requested value. The program calling web() should decide how long it wishes to wait for a response (default is 300 seconds) and use setTimeout() ro reset this value accordingly.
private static Applet busyApp = null; Set when a new host web is registered and reset to null only when it has finished registering its Site instance. Neither web() or site() will return a value for index busyApp until this value has been reset.
private static int timeout = 300; Timeout interval for waitForHost() method; default is 300 seconds. May be reset (e.g., by client applet) using setTimeout().
private static int timer = 0; Accumulates delay interval in waitForHost();
The next two methods implement a timeout period (default is 300 seconds) during which a client applet's attempt to get a reference to a host applet will delay returning a null value to give the host time to register itself. To avoid runtime errors, the client should test the applet() method's return value before attempting to proceed.
class methods public static Container applet(int id) Method returns applet indexed by id. Permits a client applet to obtain a reference to a host applet by knowing its id.
public static Container applet(String idStr) Because the applet's id parameter is read as a string from the applet tag, this method provides a more convenient way to obtain the host's reference.
private static void waitForHost() This method is called by the two above methods. Permits waiting for the interval specified by the timeout variable to give some host applet time to register. If timeout interval is exceeded, an error message is printed to the Java console without affecting program execution.
public static void setTimeout(int num); This method sets the timeout vaiable to
num seconds.
public static boolean registerApplet(int id, Container app) This method is used by a host applet to register itself in WebSite's applets index.
public static boolean registerApplet(String idStr, Container app) Again, for convienience, an alternative method is supplied.
public static boolean removeApplet(int id) Method removes the indexed applet from WebSite.applets.
public static Web web(Container app) Method returns the instance of Web indexed in WebSite.webs by app.
public static boolean registerWeb(Container app, Web aWeb) Method registers an instance aWeb of Web in WebSite.webs using the associated (host) applet app as the key.
public static boolean removeWeb(Container app) Method removes the indexed Web instance from WebSite.webs.
public static Site site(Container app) Method first calls waitForAppNotBusy(app) and then returns the instance of Site indexed in WebSite.sites by app. Note that a timeout interval is NOT implemented in this case. Except during debugging, a host which has registered itself with WebSite can be expected to successfully register its Site instance as well.
private static void waitForAppNotBusy(Container app) This method is called by the above method. It firsts calls waitForHost() and then loops until it finds that the specified applet app is not that referenced by the flag busyApp.
public static boolean registerSite(Container app, Site aSite) Method registers an instance aWeb of Web in WebSite.webs using the associated (host) applet app as the key.
public static boolean removeSite(Container app) Method removes the indexed Site instance from WebSite.sites.

Web. The class whose instances encapsulate data having to do with the website currently deployed (e.g., user data such as browser, computing platform, and screen resolution) and its user interface components (e.g., banner, footer, document, etc). Subclasses of Web manage updating of the user interface.

package earthstones
import java.awt.*;
java.applet.*;
java.util.*;
java.net.*;
class declaration public class Web extends Object
static constants public static final int DEFAULT_CURSOR_STATE = 0; These constants define the cursor state.
public static final int WAIT_CURSOR_STATE = 1;
public static final int HAND_CURSOR_STATE = 2;
public static final int CHECKING_LICENSE = 0; These constants define the registration status the software.
public static final int LICENSE_VALID = 1;
public static final int LICENSE_EXPIRED = 2;
public static final int CANNOT_VERIFY = 3;
public static final int NOT_LICENSED = 4;
variables Unlike most parameters, the following variables cannot be reset in Site.web but must be hard-coded instead.
The first two variables reflect the software version.
private float version = 1.10f; The version of this software.
private float siteVersion = 1.00f; EarthStones' website version. Is reset in subclasses of Web.
The next four variables are connected with license checking of demonstration copies of the software.
protected boolean checkReg = false; If set, software is an evaluation copy and check for valid license will occur when program loads.
protected int regDays = 30; The temporary license period,
in days.
private boolean registerEach
= false;
If set, each program (i.e., applet or application) run with an evaluation copy copy of the software must be registered; otherwise registering once permits any program to be run for the duration of the temporary license period.
protected String demoReg = "Home/Tips/02/Text.htm"; Location of the HTML file to be displayed to the user of an unregistered evaluation copy of the software. This file location is interpreted as relative to the root directory specified by the Site.webServer variable.
The major user-interface elements supported by Web. Subclasses such as JavaWeb define and support additional elements.
protected Container webApp = null; The host applet which created this Web instance.
protected DocumentPanel document = null; The website's main document panel.
protected DocumentPanel graphic = null; A second instance of document panel implemented in JavaWeb typically for display of a graphic image. Not supported by Web but defined here for convenience in coding certain DocumentPanel methods.
protected SplashPanel splash = null; The Web's splash panel.
protected Panel dialog = null; The website's dialog panel used to display messages, including on-mouseover hints.
Variables reflecting the Web's current state.
protected Page thePage = null; The current page.
protected GImage theImage = null; The image currently displayed in the graphic panel.
The next variable reflects the software's current license status.
protected int regStatus
= CHECKING_LICENSE;
The temporary license status
for evaluation software;
Variables reflecting data about the current viewer. These screen-related variables are set in init() by a call to setScreenParams().
protected String resolution = null; The user's screen resolution (e.g., 1024x768, 800x600, etc.)
protected float resFactor; A scale factor corresponding to the screen resolution (e.g., 1.00f, 0.781f = 800/1024).
protected int colorDepth = 0; The color depth of the user's monitor: 4 (16 colors), 8 (256 colors), 16 (65536 colors).
protected String browser = "IE4 4"; The user's browser and browser version.
protected String platform = "Win 95"; The user's computing platform.
protected boolean zFirstOnTop = true; Reflects the stacking order for components.
When set, the first of two overlapping
components will appear on top; otherwise,
the last will be on top. Set in init(),
is a function of browser and platform.
Variables whose values depend upon the above user data as well as parameters defined in the Site object.
protected int defaultGraphicWidth; The default width of the graphic panel.
protected int baseHtmlFontSize; The default HTML font size.
protected int baseFontSize; The default Java font size.
protected int captionFontSize; The default Java caption font size.
protected String baseFont; The default Java font face.
baseHtmlFont; The default HTML font face.
These parameter's are all properties of the default Java font, given values for baseFont and baseFontSize.
protected int baseFontheight;
protected int baseMaxascent;
protected int baseLeading;
protected int baseMaxdescent;
protected int baseAddabove;
protected int baseAddbelow;
These variables provide services to other components.
protected Image offScr; These next two variables provide the off-screen image and graphics context for double-buffering type operations.
protected Graphics offScrG;
protected Random rand; Pseudo-random number generator used to display randomly-selected images.
These flags are used by Web and other components which have access to it.
protected boolean killSplash = false; When found to be set, splash screen is hidden.
protected boolean debug = false; When set in applet tag, error messages are printed to Java console.
protected boolean isLoaded = false; Set to true when Web instance has finished loading.
protected boolean jumping = false; Set when jumping to Portfolio page to prevent image from being reloaded.
private int hostId; The host id of the applet creating this
web instance. Read from its applet tag.
private int cursorState
= DEFAULT_CURSOR_STATE;
Stores the cursor's current state.
private int waitCursors = 0; This variable is incremented and decremented   whenever the wait cursor is set and cleared.
constructors Web() Method returns applet indexed by id. Permits a client applet to obtain a reference to a host applet by knowing its id.
Web(Container apl) This is the typical constructor which associates the Web instance with the applet which created it and calls init().
methods public final void init() 1) Sets default value of autoLoad variable (true).
2) Initializes variables offScr, offScrG, and random.
3) Calls setScreenParameters().
4) Reads debug, platform, browser, and autoLoad parameters from webApp's applet tag and, if debut is set, prints their values to the Java consolole along with the value of version hardcoded into Web.
5) Reads webApp's id parameter and, if found, registers webApp with WebSite as a host applet.
6) Registers this Web instance with WebSite.
7) Sets isLoaded to signal that loading of Web instance has completed.
8) Creates an instance of Site and calls its waitUntilLoaded() method.
9) Registers Site instance with WebSite.
10) Calls zFirstOnTop() and setDefaultFontMetrics().
11) Calls setSplash().
12) Calls checkRegistration().
Note: Any remaining applet tags are read by Site.loadTags() which is called during the initialization of the Site instance.
public static String getParameter(Container app, String name) Reads and returns the string value of the name parameter of applet app.
Although Web itself can be instantiated (i.e., it is not an abstract class) the next two methods must be overridden and implemented in any Web subclasses in order to automatically manage loading and update all of the website's user-interface elements.
public void load() The load() method performs any additional initialization such as loading the website's default page. This method does nothing by default and should be overridden in subclasses.
public void update() The Web.update() method is called by the Page().show() method in response to a user event and is the central clearinghouse for managing the user interface. Subclasses must implement update() calls to each of its user-interface components.
protected void update(Panel pnl) This helper method is used by update() to load panel pnl in its own thread by creating a new thread object associated with pnl and then calling the thread's start() method which finally results with a call to pnl.run(). Note: NN 3 doesn't like something about this approach, so for this browser multithreaded loading of UI panels is turned off and update(pnl) simply calls pnl.run().
The next several methods are used to accomodate the asynchronous nature of networked communications.
public void waitToKillSplash(SplashPanel spl) This method:
1) Loops while(!killSplash).
2) Then sets spl.stop = true.
3) Then loops while(!spl.canKill).
4) Finally returns.
public void waitUntilLoaded(Panel apl) Loops while(apl == null) and then returns.
public void waitUntilLoaded() Loops while(!isLoaded) and then returns.
pause(int duration) Loops for duration milliseconds and then returns.
These methods are provided as services to various components.
public final void close() This method is called by SplashPanel to stop execution of unlicensed evaluation software.
1) For applets, it calls webApp.hide() and then webApp.stop().
2) For applications, it calls weApp.close().
public URL getDocumentBase() This method provides a convenient way of obtaining the documentBase parameter for both applets and applications. Calls the getDocumentBase() method for WebApplet and WebFrame, respectively.
public boolean loadSplash() This method provides a convenient way of obtaining the loadSplash variable for both applets and applications.
public String appendPath(String p1, String p2) Sets the path href (e.g., of a hyperlink) relative to that of the path src (e,g, the HTML source document in which
the hyperlink is embedded). The user is responsible of insuring that both are meaningful path designations.
The next two private methods are called by appendPath().
private String path(String str) Returns the path of a string representing a file location (e.g., "e:/dir/subdir/file.xxx"
returns "e:/dir/subdir/".
private String parentDir(String str) Returns the parent directory of a string representing a directory path (e.g., "e:/dir/subdir/" returns "e:/dir/" Note that path("e:/dir/subdir/file.xxx") = parentDir("e:/dir/subdir/file.xxx") but != parentDir(path("e:/dir/subdir/file.xxx")).
public GImage randomImage() Returns a randomly selected GImage object from the list of such images defined by the Images.web file.
private void setScreenParameters() 1) Uses the Applet and Toolkit methods getToolkit().getScreenSize() to determine the viewer's screen resolution (e.g., 1024x768).
2) Forces this value to one of the supported values defined in Site.web and sets the variable resolution to this value.
3) Sets the variable resFactor to screenWidth/1024.f.
4) Sets the variable colorDepth to getToolkit().getColorModel().getPixelSize().
public void setDefaultFontMetrics() 1) Uses the Applet and Toolkit methods getToolkit().getFontMetrics() to obtain a FontMetrics object for the base font defined by the baseFont and baseFontSize variables.
2) Sets the corresponding values for the variables baseMaxascent, baseMaxdescent, baseFontheight, baseLeading, baseAddabove, and baseAddbelow. The latter two parameters make use of the variable addaboveFactor defined in Site.
private void setZFirstOnTop() Currently, returns true unless browser is NN or platform is Mac.
checkRegistration() If regCheck is set:
1) Adds SplashPanel.ISCHECK to current valued of splash.mode.
2) If splash panel was already running in LOGON mode, calls splash.setRegNoticeStrings(), splash.checkRegistration(), and splash.setRegResultStrings().
3) Otherwise, calls splash.startSplash().
4) Calls regStatus().

Note that we check registration status here even though nothing is done with the information because this method does not return until demochck.cgi results have returned. (Without this wait, an array out-of-bounds error is generated in attempting to display the non-HTML CGI result). Also note that SplashPanel.hide()
checks regStatus and closes program for LICENSE_EXPIRED and CANNOT_VERIFY conditions.
public int regStatus() 1) If regCheck has not been set, immediately returns LICENSE_VALID.
2) Otherwise, loops while(regStatus <= CHECKING_LICENSE) and then returns regStatus; regStatus remains set to CHECKING_LICENSE until updated a call to setRegStatus().
public void setRegStatus(int val) This method is called only by:
1) SplashPanel.checkRegistration to report the results of demochck.cgi.
2) In the case that demochck reports NOT_LICENSED, the program's load() method must either call its loadDefaultPage() method or otherwise check for the NOT_LICENSED state and load the default page specified in that method. When this is done, Form.cgiSubmit() will transparently monitor the registration form specified by Web.demoReg (i.e., a demoreg.cgi script) and update Web.regStatus upon successful registration.
public int scale(int num) This and the following method return the num parameter scaled by resFactor.
public int scale(float num)
public Frame getFrame() Returns the parent frame of the main (host) Container webApp. For applets, this is a reference to the browser's display context. For applications, this is a reference to the program's main window.
public URL setURL(String href) If a fully qualified URL is specified by href, it is used. Otherwise getDocumentBase() is used to create the URL.
public void setCursor(int thisType) 1) If thisType = Frame.WAIT_CURSOR, increments variable waitCursors() to remember how many times wait cursor has been set.
2) Calls getFrame().setCursor(thisType) to set cursor to the specified type.
3) Adds cursor state for type thisType to current value of variable cursorState.
public void clearCursor(int thisType) 1) If thisType = Frame.WAIT_CURSOR, decrements variable waitCursors.
1a) If waitCursors is now 0, removes wait cursor state from variable cursorState.
1a1) If the new value of cursorState is HAND_CURSOR_STATE, resets cursor to Frame.HAND_CURSOR.
1a2) Otherwise, resets cursor to Frame.Default_CURSOR.
1a3) Sets killSplash = true which allows splash panel to be killed.
2) If thisType = Frame.HAND_CURSOR, removes HAND_CURSOR_STATE from cursorState and resets cursor to that specified by new value of cursorState.
The next three methods allow the programmer to display an arbitrary dialog to the user which can be dismissed by clicking anywhere on the dialog's panel.
public void showDialog(Panel pnl) Displays an arbitrary panel pnl in the dialog panel. Assumes pnl handles its own repainting and that its size and shape have been set. Note: if position of pnl has been set to (-1, -1), dialog will be shown centered in webApp. This syntax allows the programmer to have complet control over what is presented to the user. Panel should indicate in some way that a mouse click will dismiss it.
public void showDialog(String msg, int wd) Shows dialog message msg in dialog panel of width wd at center of webApp. Dialog panel is bordered at top and bottom by ruling lines whose color is set to Web.defaultAccentColor() and panel's background color is set to Web.defaultHintBgColor(). Font properties are those specified by Web.defaultJavaFont() and Web.defaultJavaFontSize(). A small "Okay" appears at the panel's bottom to suggest a mouse click to dismiss.
public void showDialog(String msg, int wd, int x, int y) This syntax allows the dialog's position in webApp to be specified as well.
public Applet getParentApp(Component comp) Returns the parent applet of a given applet component comp.
public int getWidth() Returns thePage.graphicWidth(). Note that this value is already scaled for the user's screen resolution.
The following methods, used in Versions 1 and 2 of EarthStones web site, were provided for javascript calls. Internet Explorer 3 IE 3 cannot handle Java's argument overloading so isMac(ver) becomes isMacVer(ver), etc.
public boolean isMac()
public boolean isMacVer(String ver)
public boolean isWin()
public boolean isWinVer(String ver)
public boolean isNavigator()
public boolean isNavigatorVer(String ver)
public boolean isNavigatorVNum(int vNum)
public boolean isExplorer()
public boolean isExplorerVer(String ver)
public boolean isExplorerVNum(int vNum)
The next 2 methods register the major elements of the user interface with the Web instance.
public void setDocument(DocumentPanel pnl)
public void setGraphic(DocumentPanel pnl)
These methods set and return (get) various Web parameters.
public void setJumping(boolean val) Sets jumping variable.
public void setImage(GImage img) Sets theImage variable and calls update(graphic) to refresh graphic panel.
public boolean zFirstOnTop() Returns zFirstOnTop.
public Container webApp() Returns webApp.
public SplashPanel splash()
public Panel dialog()
public int regDays()
public float siteVersion()
public String demoReg()
public boolean checkReg()
public void setSiteVersion(float val)
The following methods are "load-safe": They call waitUntilLoaded() before returning a value to make sure that the Web instance has been loaded.
public String baseHtmlFont() Returns baseHtmlFont.
public String baseFont() Returns baseFont.
public float resFactor() Returns resFactor.
public String resolution() Returns resolution.
public int colorDepth() Returns colorDepth.
public int defaultGraphicWidth() Returns defaultGraphicWidth.
public int baseFontSize() Returns baseFontSize.
public int baseHtmlFontSize() Returns baseHtmlFontSize.
public int captionFontSize() Returns captionFontSize.
protected int hostId() Returns hostId.
public boolean registerEach() Returns registerEach.
These methods were provided for javascript calls in Versions 1 and 2 of EarthStones website because some browsers balked upon finding both a variable name myVariable and a method named myVariable().
public String getResolution() Returns resolution.
public float getResFactor() Returns resFactor.
public int getBaseFontSize() Returns baseFontSize.

JavaWeb. Manages an all-Java implementation of web site.

package earthstones
import java.awt.*;
java.applet.*;
java.net.*;
java.util.*;
class declaration public class JavaWeb extends Web
variables protected BannerPanel banner = null; The website's banner panel.
protected FooterPanel footer = null; The website's footer panel.
constructors JavaWeb(Container apl) Calls super(apl) for constructor of parent class.
methods public synchronized void load() Sets value of siteVersion to 3.00 and calls WebSite.site(webApp).section(null).chapter(null).page(null).show() to load the default page. Note that this default page specification will be overridden in DocumentPanel.update in the case of an unlicensed evaluation copy of the software to display a registration form instead.
public synchronized void update() 1) Calls super.update().
2) Calls update(banner).
3) Calls updateGraphic().
4) Calls update(footer).
5) Calls update(document) and moves document panel to accomodate width of graphic panel plus a gutter between these two panels.
6) Calls update(altDoc).
public synchronized void updateGraphic() This method is called by update() as well as when the footer's "next image" button is clicked to update theImage variable and the graphic panel but none of the other user-interface elements.
These methods set and return several JavaWeb's variables.
public void setBanner(BannerPanel bnr) Sets banner variable
public void setFooter(FooterPanel ftr) Sets footer variable.
public BannerPanel banner() Returns banner.
public FooterPanel footer() Returns footer.

HtmlWeb. Manages a web site in which Java applets handle everything but HTML document rendering (EarthStones Version 2 website).

package earthstones
import java.awt.*;
java.applet.*;
java.net.*;
java.util.*;
class declaration public class HtmlWeb extends Web
variables protected BannerPanel banner = null; The website's banner panel.
protected FooterPanel footer = null; The website's footer panel.
protected Graphic graphicApp = null; The applet which implements the instance graphic of GraphicPanel.
protected String HTMLPage = "aPage.htm"; The HTML document file which defines the graphic and text frames into which the Graphic applet graphicApp and the HTML documents Text.htm are, respectively, loaded.
protected int saveGraphicWidth; Saves the current value of graphicWidth for comparison with its next value.
protected boolean saveTextScroll; Saves the current value of testScroll for comparison with its next value.
protected boolean graphicIsRunning = false; Set by instance graphicApp of Graphic to signal that the applet has been reloaded and is ready to display an image.
constructors HtmlWeb(Container apl) Calls super(apl) for constructor of parent class.
methods public synchronized void load() 1) Sets value of siteVersion to 2.00.
2) Sets saveGraphicWidth to defaultGraphicWidth() and saveTextScroll to true.
3)Calls WebSite.site(webApp).section(null).chapter(null).page(null).show() to load the default page.
4) Calls preload().
public void preload() NN 3 requires that objects accessed in javascript calls be loaded prior to the accessing method is called. In this case preload();
1) Enumerates through the website's sections and preloads each of its Chapter data objects.
2) Calls banner.preload() and footer.preload() to force each of these panels to do its own preloading.
public synchronized void update() 1) Calls super.update().
2) Calls setCursor() to set cursor to Frame.WAIT_CURSOR.
3) Calls banner.update().
4) If footer has been defined, calls footer.update().
5) If either thePage.graphicWidth() or thePage.textScroll differs from their saved values: a) sets graphicIsRunning to false; b) calls loadFile(HTMLPage(), "page"); and c) calls setImage(thePage.image()). That is, when width or scroll change, Page.htm (actually, either of the identical files aPage.htm or aaPage.htm) is reloaded; Page.htm then loads Text.htm and Graphic_v2.htm. The latter reloads Graphic.class and its init() method shows the image.
6) If neither the width nor the scroll variable changes: a) If jumping is false, calls setImage(thePage.image()); otherwise, sets jumping to false; b; calls loadFile(thePage.textFile(), "text").
7) Resets saveGraphicWidth and saveTextScroll to the values corresponding to thePage.
8) Resets cursor to Frame.DEFAULT_CURSOR.
private void loadFile(String file, String frame) This private method is called by update().
private String HTMLPage() Because some browsers will fail to reload the same HTML document file using Java's showDocument() method, this method alternately returns the value "aPage.htm" and "aaPage.htm" to trick the browser into thinking it is getting a new page. In fact, these two versions of Page.htm are identical. They contain javascript code which queries BannerApp for data about the current page thePage.
These methods set and return HtmlWeb's variables.
public void setGraphicApp(Graphic gr)
public Graphic graphicApp()
public void setImage(GImage img)
public GImage getImage()
These methods are used by javascript and provide an interface for theHTMLPage() files aPage.htm and aaPage.htm. They can
also be executed in JavaWeb by the special syntax of the Link.execute() method.
public void showPage(String sc, String ch, String pg) Encapsulates the call:
WebSite.site(webApp).[cont]
section(sc).[cont]
chapter(ch).page(pg).show().
public void showPortfolio(int chNum) Encapsulates the call:
WebSite.site(webApp).[cont]
section("Portfolio").[cont]
chapter(theChp).[cont]
page(null).show()
where theChp = [cont]
(String)WebSite.[cont]
site(webApp).[cont]
section("Portfolio").[cont]
chapters().idList().[cont]
elementAt(chNum).
These methods set and return several JavaWeb's variables.
public void setBanner(BannerPanel bnr) Sets banner variable
public void setFooter(FooterPanel ftr) Sets footer variable.
public BannerPanel banner() Returns banner.
public FooterPanel footer() Returns footer.