oracle.ide.extension

Class HashStructureElementVisitor

java.lang.Object

javax.ide.extension.ElementVisitor

oracle.ide.extension.HashStructureElementVisitor

public final class HashStructureElementVisitor
extends ElementVisitor

A generic ElementVisitor for unmarshalling extension manifest (extension.xml) elements into a HashStructure. In order for the automatic unmarshalling to occur without errors, the XML must follow a particular format. Consider the following example, where the <my-hook> element is unmarshalled by HashStructureElementVisitor:

   <my-hook version="2.0">
       <feature name="${KILLER_APP}" id="killer.app.id">
           <display description="${KILLER_APP_DESCRIPTION}"
                    icon="res:${KILLER_APP_ICON}"
                    welcome-page="uri:oracle.killerapp/welcome.html">
              Text within the display element.
           </display>
       </feature>
       <thing name="one">1</thing>
       <thing name="two">2</thing>
   </my-hook>

If the unmarshalled HashStructure for <my-hook> were assigned to a variable named myhook, the properties within my-hook could be obtained using the following code:

     String version = myhook.getString( "version" );    //  "2.0"
     String name = myhook.getString( "feature/name" );  //  dereferenced value of ${KILLER_APP}
     String id = myhook.getString( "feature/id" );      //  "killer.app.id"
     String description = myhook.getString( "feature/display/description" );
     URL icon = myhook.getURL( "feature/display/icon" );
     URL welcomePage = myhook.getURL( "feature/display/welcome-page" );
     String text = myhook.getString( "feature/display/#text" );  // Whitespace is trimmed
     List things = myhook.getAsList( "thing" );  // Each item will be a HashStructure

In greater detail, the unmarshalling occurs according to the following rules:

• Every element is a HashStructure, even empty elements or elements with only text.
• The text of an element is stored as a "#text" child.
• When an attribute value begins with "uri:" the portion after the colon is taken to be a path, which may be relative to the extension jar file's location or absolute.
• When an attribute value begins with "res:" the portion after the colon is taken to be a path (absolute or relative) to a resource that can be found via the extension-resource-bundle's Class.getResource(..) method. (The "res:" support is implemented at the JSR 198 level.)
• When there are multiple elements of the same name, they are each converted into a HashStructure and collected into a ListStructure. This collecting into a ListStructure only occurs if there are actually multiple elements with the same name. When only one element with a particular name is present, no ListStructure is created for it. To deal with this situation uniformly, so that no boilerplate code is necessary for checking if an unmarshalled 1..N property is a HashStructure or ListStructure, use the HashStructure.getAsList(java.lang.String) method to get a List every time.
• In the highly unusual case where an attribute has the same local name as one or more child elements, they will all be put into a ListStructure, with the first item in the list being a String (for the attribute) and remaining items being HashStructure instances (for the elements). Because the items in such a list are not of the same time, this is an awkward case. It would be much better to choose an XML syntax that does not lead to this situation.

The macro-like expressions such as ${KILLER_APP} are resolved and expanded according to the following rules:

1. If the macro name matches a pre-defined JSR 198 macro, it is expanded to that value.
2. Otherwise, if the macro name matches a resource key in the extension's resource bundle, it is expanded to that resource value.
3. Otherwise, the text is taken literally.

After macros have been expanded, there are two special syntaxes recognized:

• If the attribute value begins with "res:", the part after the colon is interpreted as a path (absolute if it begins with a forward slash; relative otherwise) to a resource file. The extension's resource bundle's Class is used, calling getResource() on it to resolve the path to a URL. This form is most often used when referencing icons, images, or configuration files that can be found on the classpath.
• If the attribute value begins with "uri:", the part after the colon is interpreted as a path (absolute if it begins with a forward slash; relative otherwise) to a file relative to the extension's jar file. This form is used when referencing files that are not on the classpath but can be found in relation to the extension jar.

This class is currently final because it has no behavior that can be overridden in a subclass. To provide customized behavior based on this class, use the decorator design pattern instead.

Since:

11.0

Nested Class Summary

Nested classes/interfaces inherited from class javax.ide.extension.ElementVisitor

ElementVisitor.ResourceBundleProvider

Field Summary

Fields inherited from class javax.ide.extension.ElementVisitor

KEY_LOCATOR

Constructor Summary

Constructors

Constructor and Description
HashStructureElementVisitor() Creates a new HashStructureElementVisitor which will store unmarshalled properties into a new HashStructure instance.
HashStructureElementVisitor(HashStructure root) Creates a new HashStructureElementVisitor which will store unmarshalled properties into the specified HashStructure instance.

Method Summary

Modifier and Type	Method and Description
void	end(ElementEndContext context) Visit the end tag of an xml element.
HashStructure	getHashStructure() Returns the HashStructure where this HashStructureElementVisitor unmarshalled its properties.
void	merge(HashStructureElementVisitor separateElementVisitor) Copies the data from the given HashStructureElementVisitor instance into this HashStructureElementVisitor's HashStructure.
void	start(ElementStartContext context) Visit the start tag of an xml element.
void	turnElementCounterOn() Turns element counting so that their order can be reconstructed later from the hash structure content.

Methods inherited from class javax.ide.extension.ElementVisitor

getAttributeHelper, getClassLoader, getMetaClassLoader, getResourceBundle, getResourceBundleProvider, getTextHelper, log, log, setResourceBundleProvider

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HashStructureElementVisitor

public HashStructureElementVisitor()

Creates a new HashStructureElementVisitor which will store unmarshalled properties into a new HashStructure instance.

HashStructureElementVisitor

public HashStructureElementVisitor(HashStructure root)

Creates a new HashStructureElementVisitor which will store unmarshalled properties into the specified HashStructure instance.

Parameters:

root - The HashStructure where properties unmarshalled from the extension manifest will be stored.

Method Detail

getHashStructure

public final HashStructure getHashStructure()

Returns the HashStructure where this HashStructureElementVisitor unmarshalled its properties.

Returns:

the HashStructure containing unmarshalled extension.xml properties

start

public final void start(ElementStartContext context)

Description copied from class: ElementVisitor

Visit the start tag of an xml element.

This implementation does nothing.

Overrides:

start in class ElementVisitor

Parameters:

context - information about the xml start tag.

end

public final void end(ElementEndContext context)

Description copied from class: ElementVisitor

Visit the end tag of an xml element.

This implementation does nothing.

Overrides:

end in class ElementVisitor

Parameters:

context - information about the xml end tag.

merge

public void merge(HashStructureElementVisitor separateElementVisitor)

Copies the data from the given HashStructureElementVisitor instance into this HashStructureElementVisitor's HashStructure. The data is merged together in the same way as if this visitor had been used to parse the data originally.

Parameters:

separateElementVisitor -

turnElementCounterOn

public void turnElementCounterOn()

Turns element counting so that their order can be reconstructed later from the hash structure content.