XML Model SPIs

How to Register a Provider

XML Code Completion ("XCC") SPI Requirements

XML Phenomens to be Completed

• pairing end tag (must be solved by a client)
• element name and content
• attribute name and value (enumerated, ...)
• namespace prefix (namespaces declared)
• general reference name
• parameter reference name
• prolog content (must be solved by a client)

XCC Context

• Current namespace (possibly derived from parents)
• Parents
• Siblings
• Attributes (what about default ones)

Entity Prolog

extra handling is easy no grammar required

DTD Stuff

what about it? exclude this support in GrammarQuery

XCC Interface

well formed document

document history based completion (at least pairing tags)

DTD grammar based completion

content is forced by a DTD grammar

Schema grammar based completion

must be namespace aware

Integration with Text Editor

Narrowing Context

whitespace in content

complete element name, the first option is pairing end tag

<ns:prefix

complete element name starting with the prefix defined in given ns (detect that document use : for ordinary naming)

</prefix

complete pairing end tag starting with prefix

<prefix

complete element name or namespace starting with the prefix

[prefix after] whitespace in element start tag markup

complete namespace prefix of attribute name (global)

&prefix

list all declared general entities starting with prefix

pseudo attribute name in prolog

complete one of: version, standalone, encoding

pseudo attribute value in prolog

complete from list of known values (encodings)

Integration with Tree Editor

Narrowing Context

Catalogs Package

Maintainer: Petr Kuzel

Updated on: 6th feb 2001

Introduction

What is catalog?

In order to use a variety of XML tools in a variety of computer environments, the problem of addressing resources that are inaccessible using their explicit system identifiers must be solved.

The short term solution to this problem is to define an entity catalog that handles the simple cases of mapping an external entity's public identifier and/or system identifier to an alternate URI. This solution allows for a probably system-dependent but application-independent catalog. Though it does not handle all issues that a combination of a complete entity manager and storage manager addresses, it simplifies both the use of multiple products in a great majority of cases and the task of processing documents on different systems.

What is Entity Resolution?

Entity resolution is the process that an XML processor goes through when it has been requested to find another file^[1] in the course of processing the file it's working on. The XML processor knows labelling information about the file such as its system identifier and possibly a name, public identifier, and so forth. These identifiers can be used to determine the actual location of the desired external file. This determination process (which "maps" the known labelling information into an actual location) is called an entity resolution, and the file that contains the specific mapping information is called the entity resolution catalog.

[1] file is used here for simplicity, but could be any other resource consisting of such things as declarations, a parsed entity, an unparsed entity, etc.

 + XML Catalog Browser ~-------------------------{root}
   + System Catalog [ro] ~--------------------{catalog}
   | + -//Netbeans Toolbars DTD//EN ~---{catalog entry}
   | + -//Other system DTD//EN
   | + -//X Catalog//EN
   + My SOCAT [ro]
   + My XCatalog [rw]
     + +//WML 1.1//EN

Catalog providers package

Maintainer: Petr Kuzel

Updated on: 6th feb 2001

<!ELEMENT XMLCatalog (Map | Remap | Delegate | Extend | Base)+>

<!ELEMENT Map EMPTY>
<!ATTLIST Map
  PublicId CDATA #REQUIRED
  HRef CDATA #REQUIRED>

<!ELEMENT Remap EMPTY>
<!ATTLIST Remap
  SystemId CDATA #REQUIRED
  HRef CDATA #REQUIRED>

<!ELEMENT Delegate EMPTY>
<!ATTLIST Delegate
  PublicId CDATA #REQUIRED
  HRef CDATA #REQUIRED>

<!ELEMENT Extend EMPTY>
<!ATTLIST Extend
  HRef CDATA #REQUIRED>

<!ELEMENT Base EMPTY>
<!ATTLIST Base
  HRef CDATA #REQUIRED>

XML Entity Catalog SPI

Maintainer: Petr Kuzel

Updated on: 31st June 2001

SPI Overview

SPI Implementator Guide

Every SPI implementation must implement interface {@link org.netbeans.modules.xml.catalog.spi.CatalogReader CatalogReader} allowing quering catalog for entries, refreshing its content and optionaly listening on its content.

An SPI implementation should implement following interfaces:

• {@link org.netbeans.modules.xml.catalog.spi.CatalogDescriptor CatalogDescriptor} describing catalog instance
• {@link org.netbeans.modules.xml.catalog.spi.CatalogWriter CatalogWriter} allowing to modify catalog entries
• SAX's org.xml.sax.EntityResolver if it can resolve more complicated cases than public => system ID mappings

NetBeans IDE Platform Integration

  <folder name="Services">
    <folder name="Hidden">
      <file name="my-company-netbeans-catalog-impl-MyProvider.instance" />
    </filder>
  </folder>

Using CatalogProvider just provides a kind of factory, so that the user can add one or more instances of the catalog at will. You may instead register a CatalogReader instance directly in your layer in the folder Plugins/XML/UserCatalogs/; such catalogs will be preinstalled and not deletable.

Forte for Java 3.0 Specifics Feature

XML Cookies

Simple DTD based Completion Grammar Package

This simplification is same as for HTML grammar provided by editor module.

On the other hand there it prepared class {@link ContentModel} that handles it. It is ready to be integrated.

Model SPI Description

Contributors please keep dependencies as small as possible. Generally DOM and Java Core APIs are permitted.

TODO

• Add possibility to set TreeFactory e.g. protected AbstractTreeCustomizer.getFactory()

Document Based DOM

Open Issues

Entity references cannot be properly resolved as DTD part and all external stuff is completelly ignored. A callback interface can be established for this purpose:

public interface EntityReferenceResolver {
    NodeList resolveEntityReference(EntityReference ref) throws IOException;
}

Attribute values should report DTD defined defaults as it cannot be also retrieved from token chain. In this case can be also introduced a callback or does not stay fully with DOM spec. But is it violation of spec? We are contruction DOM without DTD knowledge so there are not default attributes declared.

How to use this package

Developer needs to postprocess generated files by erasing all generated *Stream classes and sources. All .jj grammars import lib subpackage which contains proper implementation of these interfaces/classes.

This solution is not clean but current JavaCC and editor module does not support better solution. Look for lexer.netbeans.org that should provide stream based lexical analysis for editor that is more suitable for JavaCC generated code.

XMLSyntax uses more general state stack than DTDSyntax integer array. (It can be easily copy pasted to DTDSyntax shared text section.)

XML Generators Package

Maintainer: Petr Kuzel and Libor Kramolis

Updated on: 11th Jun 2001

Introduction

To do

What about sample implementation generate attributes switch

1. Java code generator creating SAX parser of documents following given DTD.
2. Java code generator creating DOM scanner (a visitor) of DOM following given DTD.
3. DTD generator guessing it from an XML document.
4. All Java generators produces a JAXP compliant code to achieve parser neutrality.

SAX Document Handler Wizard

The generated code depends on DTD availability and therefore does not support namespaces.

Term: Parslet stay for a set of data convertors.

Input

• DTD representing static vocabulary to be recognized
• DTD mapping allowing to define mapping between the vocabulary and a code. Mapping key is and element name.
• JAXP version - version of JAXP to be used in generated methods
• SAX version - version of SAX parser to be used (depends on JAXP version)
• Output file names where generated code will be placed. There are 1-2 interfaces, 1 recognizer file and empty implementations files.

DTD to Method Mapping Step

• Data element representing (#PCDATA). It represents a data holder.
• Empty element representing EMPTY. It represents a data holder.
• Mixed element representing mixed content. It represents a data holder or a container or both.
• Container element allowing just another elements. It represents a container.

A data holder can be mapped into a handling method taking actual data and meta-data where the actual data can be a result of parsing by a parslet. It can be also ignored.

A container can be mapped into delimiter methods taking meta-data. It can be also ignored.

The generator detects all DTD declarations and fills a mapping table.

It maps data holders into handle_elementname(Object data, Attributes meta) event methods using no parslet.

It maps containers into start_elementname(Attributes meta) and end_elementname(Attributes meta).

Data Holders to Parslet Mapping Step

Versions Step

Output Destination Step

Output

Generator generates output files overwriting files that are not supposed to be modified by user. Anyway it keep a backup copy of rewritten files. Files to be automatically overwritten are parser, handler interface and parslet interface, these content is driven by the DTD file.

Wizard Reentrance

DOM Scanner

Parser Package

Maintainer: Petr Kuzel and Libor Kramolis

Updated on: 6th feb 2001

The package provides a parser suitable for XML editing tasks. There are two parsers provided.

1. A cloned implementation of Sun's JAXP 1.0 reference implementation parser. Entity resolution is patched so it is suitable for tools purposes (allows two-way). Rejected
2. ParserLoader represents a izolator implemented as filtering class loader for particular Xerces implementation. It will replace almost whole package in future.

TODO

Why Wrapper?

Status

Why so Many new

Consequence: This implementation uses very lightweight wrappers therefore only drawback it increased garbage production. It should be also handled in latest HotSpot implementations.

Overview

Class Structure

  TreeInputSource             TreeOutputResult
       |                           |
  TreeBuilder                 TreeWriter
       |                           |
       *---------> Tree -----------+

TreeInputSource

interface representing a source providing a builder available to build a tree instance from the source.

TreeStreamSource

TreeInputSource implemenation reading data from SAX's InputSource.

TreeBuilder

interface with buildDocument() returning a tree instance It returns XML or DTD tree depending on the source that provided it.

TreeStreamBuilderXercesImpl

TreeBuilder implementation provided by TreeStreamSource

TreeOutputResult

provides getWriter() returning writer writing to some output representation

TreeStreamResult

implementation of TreeOutputResult

SAX EntityResolver Replacement

TreeEntityResolver

an interface

TreeEntityManager

the void implementation

Creator Interfaces Purpose

Writer Interface Purpose

Constrains Interface Purpose