HotJava HTML Component

Purpose

The HotJava HTML Component is the encapsulation of about 80 percent of what a web browser does. Specifically, this is the HTML parsing and rendering engine used in the HotJava Browser. This component is a candidate for use in any application that requires display of documents or navigation similar to that found in web browsers.

documentString - the URL for the current document as a string.

HotJavaBrowserBean()
clone()

setDocumentString() - set (and display) a document by specifying a URL as a string.
find() - search for a given string in the current document.
print()- print the current document.

About This Document

This document describes the HTML JavaBean component. It is intended for both "component assemblers" who will be instantiating and connecting the bean in builder applications as well as Java developers who will be programatically accessing the component. It assumes that you are already familiar with JavaBeans. If terms like property, event, method, introspection, or serialization are unfamiliar, you may want to refer to the JavaBeans documentation or take the JavaBeans tutorial.

At A Glance
About This Document
Class Description
Summaries
Property Summary
Method Summary
Event Summary
Alphabetical Reference
Properties
Methods
Events
Supporting Classes
See Also

The HotJava HTML Component is a single, monolithic panel class that complies with the JavaBeans 1.0 specification. While the major browser functionality is contained within this single bean, there are also the Authenticator, Document Stack, and System State beans which provide supporting functionality.

There is also a normal Java class behind the bean that implements the methods. This class could also be used in Java applications. The danger with this is upward compatibility. If in the future browser functionality is provided as a collection of beans, rather than one, then the panel class becomes obsolete. Compatibility with the monolithic bean component will be maintained via bean aggregation, but the panel class, if used in Java applications, will have no such guarantee.

To support the possible future development directions, the intent is to keep this API as minimal as possible, while providing a full featured product. This is a difficult balance between making it easier to use, and providing an API that won't need to be broken in the future.

There are two types of security concerns with the HTML component: The security manager, which determines what it can do, and dealing with secure connections.

An HTML component presents a difficult situation. The Bean specification says that security management is the responsibility of the bean container. Beans that are to be used everywhere need to be able to run under a security manager, while beans that are application specific may not need to. The HTML component is unique in that it is a bean that can have other beans or Java applets within it that can come from unknown sources, i.e. the web. If the HTML component were to just let its container worry about security, as recommended by the Bean specification, you could easily get into a situation where you are browsing the web and running applets totally unprotected. To protect against this, when the bean is instantiated, if it doesn't detect a security manager it will install one. The installed security manager will only affect applets within the bean. This still allows applets to take advantage of a lenient container-supplied security manager, but it does provide good default security behavior. We also provide an option for the case where an application needs to have its own security manager in addition to the HTML Component's security manager. The application can have both managers running simultaneously by instantiating the DelegatingSecurityManager. The only drawback to this method is that the DelegatingSecurityManager assumes that the HTML Component Jar file is on the CLASSPATH.

To deal with secure connections, we need to handle authentication. Dealing with authentication means supplying a user interface, something we are trying to avoid in the bean. As a compromise, we are breaking the monolithic model, and supplying the HotJava Authenticator Bean. This release defines the interface used by this bean, and provides a default implementation. Developers may use this version or override its behavior. If the authenticator bean is not wired into the container, the HTML component will work fine, but it will not be able to connect to secure sites.

The right mouse pop-up menu is not implemented in the HTML component itself. If the client wishes to provide this functionality, they can listen for a right mouse button down event, display their own menu, and use the menu select information with the IndicatedElement property to perform any requested function.

Also note that this bean doesn't directly support a history list or forward/back behavior. That functionality may be provided by the client, or by using the HotJava Document Stack.

A BeanInfo class, HotJavaBrowserBeanBeanInfo, explicitly provides information for properties, events, and methods.

Rather than providing a BeanCustomizer class, the relevant state of the HTML component may be accessed through the use of the HotJava System State bean.

EventListener Interfaces:

BrowserHistoryListener  PropertyChangeListener  VetoableChangeListener

EventListener Interfaces:

BrowserHistoryListener  ComponentListener

charset [bound] - character set used to translate into Unicode

Type: String
Get: getCharset()
Set: setCharset()

currentDocument [constrained][bound] - the document being displayed

Type: CurrentDocument
Get: getCurrentDocument()
Set: setCurrentDocument()

documentReloadable [bound] - true when the document can be reloaded

Type: boolean
Get: isDocumentReloadable()
Set: none

documentSource [bound] - the input stream for the current document

Type: Reader
Get: getDocumentSource()
Set: setDocumentSource()

documentString [bound] - the URL for the current document as a string

Type: String
Get: getDocumentString()
Set: setDocumentString()

documentTitle [bound] - the title of the current document

Type: String
Get: getDocumentTitle()
Set: none

documentURL [bound] - the URL for the current document

Type: URL
Get: getDocumentURL()
Set: setDocumentURL()

errorMessage [bound] - the most recent error string

Type: String
Get: getErrorMessage()
Set: none

frameList [bound] indexed - the names of all HTML frames

Type: String[]
Get: getFrameList()
Set: none

indicatedElement [bound] - the link (if any) under the cursor

Type: ElementInfo
Get: getIndicatedElement()
Set: none

loadingProgress [bound] - the most recent progress information during document loading

Type: double
Get: getLoadingProgress()
Set: none

secureConnection [bound] - true when the current connection is secure

Type: boolean
Get: isSecureConnection()
Set: none

selection [bound] - the user's current selection

Type: DocumentSelection
Get: getSelection()
Set: none

statusMessage [bound] - the most recent status message

Type: String
Get: getStatusMessage()
Set: none

void addBrowserHistoryListener(BrowserHistoryListener l)

Add a listener to receive executeHistoryCommand messages.
See also: removeBrowserHistoryListener(), addPropertyChangeListener(), removePropertyChangeListener(), addVetoableChangeListener(), removeVetoableChangeListener().

void addPropertyChangeListener(PropertyChangeListener l)

Add a listener for post-notification of changes in a bound property.
See also: removePropertyChangeListener(), addBrowserHistoryListener(), removeBrowserHistoryListener(), addVetoableChangeListener(), removeVetoableChangeListener().

void addVetoableChangeListener(VetoableChangeListener l)

Add a listener for pre-notification of changes in a constrained property.
See also: removeVetoableChangeListener(), addBrowserHistoryListener(), removeBrowserHistoryListener(), addPropertyChangeListener(), removePropertyChangeListener().

void clearImageCache()

Clear the image cache. Calling this method will dump all cached images.

HotJavaBrowserBean clone()

This method clones the current browser panel and returns it to the client. This is intended to be used in response to user requests for a new browser window. If the client wishes to support this feature, they can do so by cloning the browser panel, and adding it to a new Frame. This way all context, POST information, etc. is preserved.
See also: HotJavaBrowserBean().

void executeHistoryCommand(BrowserHistoryEvent evt)

Processes a BrowserHistoryEvent. This method is implemented as part of the BrowserHistoryListener interface. It is used to enable the stack bean to receive history notifications from the browser bean. Make no assumptions about the internals of this event i.e treat this an an opaque event.

int find(int pos, String val)

Searches the current document for text matching val starting at position pos. Position 0 is the beginning of the document. The document is then scrolled to bring the first match into view, and the position of that match is returned, and can be passed to subsequent calls to find the next occurrence. -1 is returned if no match is found. Other then the special values mentioned, the client should not make any assumptions about the meaning of position.

String getCharset()

Get the charset property. This is a bound property, normally set by a MIME header in the HTTP connection. This setting affects the character set that is used to translate the incoming byte stream into Unicode.
See also: setCharset().

CurrentDocument getCurrentDocument()

Get the currentDocument property: a class representing the currently viewed document. The currentDocument property may be null if the browser is not currently viewing a specific location.
See also: setCurrentDocument(), getDocumentString(), getDocumentURL().

Reader getDocumentSource()

Get the HTML source for the current document.
See also: setDocumentSource().

String getDocumentString()

Get the documentString property: the URL of the currently viewed document as a string. It may be null if the browser is not currently viewing a specific location.
See also: setDocumentString(), getDocumentURL(), getCurrentDocument().

String getDocumentTitle()

Get the documentTitle property. This is a bound property, set when loading a new document to the value specified by the TITLE HTML tag. May be null.

URL getDocumentURL()

Get the documentURL property: the URL of the currently viewed document. It may be null if the browser is not currently viewing a specific location.
See also: setDocumentURL(), getDocumentString(), getCurrentDocument().

String getErrorMessage()

Get the errorMessage property. This is a bound property, set whenever an error is encountered.

String[] getFrameList()

Get the frameList property. This is a bound, indexed property. When frames are created or destroyed, their names are added or removed from this list. This information is mostly useful for clients who are maintaining multiple bean instances, each with its own set of frames, as a document in one may try to force navigation in a frame in another.

String getFrameList(int index)

Get a specific frame by index from the frameList.

ElementInfo getIndicatedElement()

Get the indicatedElement property. This is a bound property whose value is the link (if any) under the cursor. The ElementInfo class contains the inline image URL (if any), the href URL (if any), the alternate text (if any), and the MouseEvent data that triggered the change (Up, Down, or Moved if the links change).
See also: getSelection().

double getLoadingProgress()

Get the loadingProgress property. This is a bound property used to provide progress information during the loading of a document, and its components. The value returned is a double precision floating point number that will vary between 0 and 1. This value will indicate a composite of the load state of all the different items being loaded. This property will always be set to 0 at the start of loading, and to 1 when loading finishes.
See also: isDocumentReloadable() reload().

DocumentSelection getSelection()

Get the selection property. This is a bound property, set whenever the user highlights a portion of the displayed document. The return value is a DocumentSelection containing the selected area in text and raw HTML.
See also: getIndicatedElement().

String getStatusMessage()

Get the statusMessage property. This is a bound property, set whenever the current status changes.

HotJavaBrowserBean()

Default constructor. Used to construct all instances of the browser bean. If a security manager is to be installed, it will be done here. The browser panel is ultimately derived from ScrollPanel, so it is scrollable.
See also: clone().

boolean isDocumentReloadable()

Is the current document reloadable? Returns true if there is a current, valid document. This is a bound property.
See also: reload().

boolean isSecureConnection()

Get the secureConnection property. This is a bound property, set whenever the security of the connection changes. It is true when the current connection is secure.

void print()

Prints the contents of the browser panel. Intended to be invoked directly by controls like a "Print" button.

void print(PrintJob job)

Prints the contents of the browser panel, with additional parameters determined by the PrintJob.

void reload()

Reload the current document if possible. Ignored if there is no document to reload.
See also: isDocumentReloadable(), getLoadingProgress(), stopLoading().

void removeBrowserHistoryListener(BrowserHistoryListener l)

Remove a listener that had been receiving executeHistoryCommand messages. addPropertyChangeListener(), removePropertyChangeListener(), addVetoableChangeListener(), removeVetoableChangeListener().
See also: addBrowserHistoryListener().

void removePropertyChangeListener(PropertyChangeListener l)

Remove a listener for post-notification of changes in a bound property.
See also: addPropertyChangeListener(), addBrowserHistoryListener(), removeBrowserHistoryListener(), addVetoableChangeListener(), removeVetoableChangeListener().

void removeVetoableChangeListener(VetoableChangeListener l)

Remove a listener for pre-notification of changes in a constrained property.
See also: addVetoableChangeListener(), addBrowserHistoryListener(), removeBrowserHistoryListener(), addPropertyChangeListener(), removePropertyChangeListener().

void setCharset(String charset)

Set the charset property. This is a bound property, normally set by a MIME header in the HTTP connection. This setting affects the character set that is used to translate the incoming byte stream into Unicode.
See also: getCharset().

void setCurrentDocument(CurrentDocument doc)

Set the currentDocument property: a class containing the String, URL, frame name of the currently viewed document, and a hint whether or not a new window should be created with a cloned bean. This last value is a hint only, and will always be false when received as a bound property change. It will have no effect in the bean itself. Setting this property has the side effect of initiating navigation to the new URL.
This is a constrained property, so the change of state can be vetoed by the listener. If it is not vetoed the document at that location will be fetched and displayed in the frame named, if it exists. If the frame name is not null, and does not exist in the bean, then all frames will be removed, and the document displayed, with the frame given the indicated name. This change should be listened to by clients who might wish to create another bean instance for the indicated frame, rather than using this one, based on the supplied hint, or their own criteria. If the client has already created other bean instances, with named frames, and the frame named in this property matches one, then this property should be vetoed, and set in the other bean.
See also: getCurrentDocument(), getDocumentString(), getDocumentURL().

void setDocumentSource(Reader source)

Set the document source property. This is a bound property that can be used to cause HTML source to be rendered. When this method is used directly (as opposed to being set as part of the navigation process), the document and documentURL properties are first set to null. If these changes are not vetoed, then HTML source from the Reader will be parsed and rendered.
See also: getDocumentSource().

void setDocumentString(String url)

Set the documentString property: the URL of the currently viewed document as a string. This has the side effect of initiating navigation to the new URL. This is merely a bound property, but setting it will trigger setting of the documentURL property, and the currentDocument property, which is vetoable.
See also: getDocumentString(), setDocumentURL(), setCurrentDocument().

void setDocumentURL(URL url)

Set the documentURL property: the URL of the currently viewed document. This has a side effect of initiating navigation to the new URL. This is a bound property, but setting it will trigger setting of the documentString (if it indicates a different URL) property, and the currentDocument property, which is vetoable.
See also: getDocumentURL(), getDocumentString(), getCurrentDocument().

void stopLoading()

Stop loading of current document if possible. Ignored if done loading.
See also: getLoadingProgress(), reload().

void stop()

Stop animations, or stop formatting the current page. Useful if the container holding the bean is hidden from view.
See also: start().

void start()

Start animations on the current page and/or finish formatting the current page.
See also: stop().

Most events are either pre-notifications of property change with the option for the listener to veto (constrained), or post-notifcations of property change (bound). Listeners may register for pre-notification of constrained properties with addVetoableChangeListener() and/or post-notifcation of bound properties with addPropertyChangeListener().

Communication with the HotJava Document Stack is handled by means of the BrowserHistoryListener interface. Messages of the form executeHistoryCommand() are sent to the document stack to notify of changes in the current document state or to clear the history.

EventListener Interfaces:	BrowserHistoryListener  PropertyChangeListener  VetoableChangeListener
EventObjects:	BrowserHistoryEvent  PropertyChangeEvent

The HotJava Document Stack also sends the executeHistoryCommand() method to update the HTML component as "next" and "previous" operations are performed. Hence, this component is also a BrowserHistoryListener.

This component is also intended to be the target of button pushed and other component activation, and therefore implements ComponentListener.

EventListener Interfaces:	BrowserHistoryListener  ComponentListener
EventObjects:	BrowserHistoryEvent

class CurrentDocument { 
public String documentString;   // String rep of URL
public URL documentURL;         // URL
public String frameName;        // Frame document is displayed in
public boolean externalHint;    // A hint given if the HTML component thinks 
                                // the client should veto the change, and 
                                // set this property on a new bean instance,
                                // or an existing instance that contains 
                                // the named frame
};

class Cookie { 
public int version;             // Cookie version
public String attribute;        // Attribute name
public String value;            // Value
public String domain;           // Domain
public String path;             // Path
public String comment; 
public Date expires;            // Exipration date
public boolean secure;          // Is this a secure cookie?
public static Cookie parseFromString( String cookieString );
public static Cookie[] parseFromString( String cookieString );
public static String[] combineAsStrings( Cookie[] cookieList );
public String toString();       // Convert to string.
};

class CookieJar { 
public CookieJar(Cookie[]);
public Cookie[] getCookies();
public boolean isIncrementalChange(CookieJar other);
public Cookie entryAdded(CookieJar other);
public Cookie entryRemoved(CookieJar other);
};

class PoolEntry { 
public String url;              // URL string of entry
public Date lastTouched;        // Expiration date of entry
public String URL;              // URL string of entry
};

class URLPool { 
public URLPool(PoolEntry[]);
public PoolEntry[] Entries();
public boolean isIncrementalChange(URLPool other);
public PoolEntry entryAdded(URLPool other);
public PoolEntry entryRemoved(URLPool other);
};

class DocumentSelection { 
public String text;             // Text of selection
public String html;             // HTML of selection
};

class ElementInfo { 
public String imageURL;         // Image link
public String hrefURL;          // HREF link
public String altText;          // Alt text
public MouseEvent event;        // source event
};

class SystemProperties {
public SystemProperties(Hashtable values)
public Hashtable getValues()
}

HotJava Browser Components
HotJava Authenticator Bean
HotJava Document Stack Bean
HotJava System State Bean
DelegatingSecurityManager