xml-xsp-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ricardo Rocha <rica...@apache.org>
Subject Deprecating the <xsp:page> root element
Date Wed, 08 Nov 2000 14:39:32 GMT
In light of the experience and understanding gained (at times
painfully) with the Cocoon1 XSP implementation, some changes
appear necessary:

One of them is the supression of the <xsp:page> root element,
which appears to be unnecessary and error-prone.

To being with, this root element always encloses one and only
one "user" root element.

Anything stated by means of attributes in <xsp:page> can also
be expressed inside the "user" root element by qualifying such
attributes with the "xsp" namespace. Thus:

  <xsp:page language="java" ...>
    <page> ... </page>
  </xsp:page>

can be shortened to:

  <page xsp:language="java" ...> ... </page>

As an added bonus, removing the <xsp:page> root element also
removes the need to declare the "xsp" namespace when no XSP tags
are actually used in the document (in fact, the "ideal" case)

The "language" attribute defaults to the default programming
language used by the XSP environment ("java" for Cocoon2, "perl"
for AxKit) so it can be safely omitted in practically all cases.

The "create-session" attribute is an ugly hack that ties XSP
with the servlet environment and should clearly be deprecated!

Its use, nevertheless, reveals the need to provide [Cocoon]
environment-specific directives that are processed prior to code
generation (more on this when we discuss decoupling code generation
from the taget source program type). This attribute could be
replaced by, e. g., a <servlet:option create-session="true"/>
directive.

The "encoding" attribute introduced in Cocoon2, should remain in
place as a root-level attribute:

  <page xsp:encoding="Cp1251" ...>

This attribute is clearly redundant with respect to the
standard directive:

  <?xml version="1.0" encoding="Cp1251"?>

Unfortunately, however, the SAX (and DOM) API's doesn't provide
a standard way of quering the parser for the  original document
encoding.

For the Java language (at least) this information is necessary
to direct the compiler to generate a class with the proper
string encoding (javac -encoding ...)

It's somewhat untasteful to include a directive like this in
the XSP language because a particular language requires it.

Probably (along the lines of the [Cocoon] environment-specific
directives suggested above) a language-specific tagset and
namespace should be defined that account for this sort of
need:

  <page java:encoding="..." ...>

As we'll see in upcoming posts (when discussing decoupling XSP
from target source program types) it is possible to use XSP's
code generation machinery for environments other than Cocoon
and web applications.

For this genericity, it's conceivable that a target XML API
can also be defined (SAX, DOM, JDOM) so that the appropriate
code is emitted and the appropriate logicsheets are selected
for code generation.

In this scenario, the following factors would govern code
generation:

- Markup language (XSP, JSP)
- Programming language (Java, Perl, ...)
- Environemnt (e.g. servlet, offline, ...)
- Target API (SAX, DOM, JDOM)
- Target source program type (Generator, Transformer, ...)

Back to our main subject...

Another use of the <xsp:page> element is to provide the top-level
context in which to import external modules and to declare class-level
logic:

  <xsp:page ...>
    <xsp:structure>
      <xsp:include>java.text.SimpleDateFormat</xsp:include>
    </xsp:structure>
    <xsp:logic>
      private static String systemTime(String formatMask) {
        return new SimpleDateFormat(formatMask).format(new Date());
      }
    </xsp:logic>
    <page> ... </page>
  </xsp:page>

In absence of a <xsp:page> root element, the same effect can be
achieved by stating that <xsp:structure> can only occur as a
top-level element, immediately below the [user] root element and
that any <xsp:logic> elements inside <xsp:structure> are to be
treated as class-level logic:

  <page xmlns:xsp="http://apache.org/xsp">
    <xsp:structure>
      <xsp:import>java.text.SimpleDateFormat</xsp:import>
      <xsp:logic>
        static String systemDate(String formatMask) {
          return new SimpleDateFormat(formatMask).format(new Date());
        }
      </xsp:logic>
    <xsp:structure>
    . . .
  </page>

Note that, in the above snippet, we have replaced <xsp:include> by
<xsp:import>.

This is another proposed change: deprecate <xsp:include> in favor
of <xsp:import>

The term "include" is usually associated with [generation-time]
inclusion semantics (think of JSP's <%include%> directive). This is
clearly not the case here. The term "import", on the other hand, is
used consistently with module import semantics in other languages
besides Java.

In regard to generation-time document inclusion, it is our opinion
that logicsheets (and external entities) make it unnecessary and
redundant.

Logicsheets can easily and uniformly account for the type of
need addressed by generation-time inclusion directives (such as
JSP's <%include%>).

Generation-time inclusion by means of external entities is highly
discuraged since it doesn't allow for the dependency checking required
to regenerate compiled programs when their source files (logichseets,
included documents) change on disk.

Finally, XInclude directives should always be resolved at _request
time_, never at compilation time.

Comments are welcome!

Ricardo

Mime
View raw message