Help

Controls

PermLinkWikiLink

Built with Seam

You can find the full source code for this website in the Seam package in the directory /examples/wiki. It is licensed under the LGPL.

Forum: Seam Users Forum ListTopic List
05. Sep 2008, 04:19 CET | Link

Hello Seam Developers,

In my quest to better understand the pages.xml file (and accompanying schema), I've been going through the pages.xsd file and I've come up with some suggestions regarding the pages.xsd - pages schema 2.0 (although these also apply to 2.1 as well).

1.) Enforcement of schema rules

The pages element contains a sequence of a choice between conversation elements and page elements unbounded so as many as you want, and after that, an unbounded number of exception elements. However, if one places the exceptions up at the top (i.e., before any page or conversation elements), the application runs just fine. IOW, the schema rule is not being enforced. This rule should either be enforced by the application or replaced with: 

<xs:element name="pages">
  <xs:complexType>
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
      <xs:element ref="pages:conversation"/>
      <xs:element ref="pages:page"/>
      <xs:element ref="pages:exception"/>
    </xs:sequence>
    <xs:attributeGroup ref="pages:attlist.pages"/>
  </xs:complexType>
</xs:element>

Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.

Other rules not being enforced (or that should ... see view-id attribute in redirect's view-id attribute) include:

  • exception element doesn't enforce order of end-conversation, http-error redirect respectively
  • both http-error and redirect allow many messages, schema reports to only allow zero or one
  • redirect view-id attribute should be of type IDREF or xs:keyref, don't want to point to a page that doesn't exist right?
  • http-error error-code attribute should be required(?)

These enforcement rules should either be taken out or they should be enforced. Leaving as is causes confusion and unwanted bug reports which may not in fact be due to bugs.

2.) Using Regex to clarify allowable values

The use of regex would greatly help narrow what a user (us app developers). For example, the view-id attribute of the page element accepts ... a view id. Why not restrict it like this: 

<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern value="/.*"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>

If one wanted, a narrowing of scope could further the selection to something like: 

<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern value="/.*\..*"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>

Or even: 

<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern
          value="/.*\.(\.seam|\.html|\.xhtml|.\jsp)"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>

But that would probably be too restrictive (someone might complain that they can't create a page called index.monkey)

Restrict page element's conversation attribute to being token scheme to being either http or https

3.) Schema Annotation/Documentation

Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.

Summary

This sort of check really should be performed at the beginning of the startup procedure and belch validation exceptions if the user has not provided a valid pages.xml file.

Anyways, these are the ones that I've had a chance to play with so there could be others. I hope this doesn't come off as trolling, intonation gets lost in forum posts and so I just wanted to be clear that I'm not writing this out of anger but rather enthusiasm about this framework and particularly understanding the pages.xsd document and being able to use it correctly. One thing that I've been really trying to avoid is potentially filing out a bug report when in fact it's simply user error ... that would be embarrassing.

Anyways, if need be I will file a JIRA report. Let me know ...

Arron

 

Beware of programmers carrying screwdrivers

9 Replies:
05. Sep 2008, 13:43 CET | Link
Arron Ferguson wrote on Sep 05, 2008 04:19:
1.) Enforcement of schema rules The pages element contains a sequence of a choice between conversation elements and page elements unbounded so as many as you want, and after that, an unbounded number of exception elements. However, if one places the exceptions up at the top (i.e., before any page or conversation elements), the application runs just fine. IOW, the schema rule is not being enforced. This rule should either be enforced by the application or replaced with: 
<xs:element name="pages">
  <xs:complexType>
    <xs:sequence minOccurs="0" maxOccurs="unbounded">
      <xs:element ref="pages:conversation"/>
      <xs:element ref="pages:page"/>
      <xs:element ref="pages:exception"/>
    </xs:sequence>
    <xs:attributeGroup ref="pages:attlist.pages"/>
  </xs:complexType>
</xs:element>

Better still: 

<xs:element name="pages">
        <xs:annotation>
            <xs:documentation>The root of a pages.xml file</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:choice minOccurs="0" maxOccurs="unbounded">
                <xs:element ref="pages:conversation"/>
                <xs:element ref="pages:page"/>
                <xs:element minOccurs="0" maxOccurs="unbounded" ref="pages:exception"/>
            </xs:choice>
            <xs:attributeGroup ref="pages:attlist.pages"/>
        </xs:complexType>
    </xs:element>

I fixed this.

Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.

I don't know XSD well enough to fix this. The rule we need is any order, end-conversation is optional, and must have either http-error OR redirect

  • both http-error and redirect allow many messages, schema reports to only allow zero or one

Only the first one will be used

  • redirect view-id attribute should be of type IDREF or xs:keyref, don't want to point to a page that doesn't exist right?

That's fine, Seam supports virtual pages, and also pages that aren't specified in pages.xml

  • http-error error-code attribute should be required(?)

Agreed. I fixed this.

2.) Using Regex to clarify allowable values The use of regex would greatly help narrow what a user (us app developers). For example, the view-id attribute of the page element accepts ... a view id. Why not restrict it like this: 
<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern value="/.*"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>

Ok, I applied: 

<xs:simpleType name="view-id">
        <xs:restriction base="xs:string">
            <xs:pattern value="(/.*)|\*"/>
        </xs:restriction>
    </xs:simpleType>

which seems correct to me

If one wanted, a narrowing of scope could further the selection to something like: 
<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern value="/.*\..*"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>
Or even: 
<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern
          value="/.*\.(\.seam|\.html|\.xhtml|.\jsp)"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>
But that would probably be too restrictive (someone might complain that they can't create a page called index.monkey)

Neither of these are valid, there is no requirement a view id must end in .*

  • Restrict page element's conversation attribute to being token

I don't think this will work, as conversations can be declared in another pages.xml file.

  • scheme to being either http or https

File an issue for this, I need to think about it.

3.) Schema Annotation/Documentation Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.

Totally agreeed. Want to write a patch with what you know/can garner from the docs? We need these for all the components.xsd as well...

This sort of check really should be performed at the beginning of the startup procedure and belch validation exceptions if the user has not provided a valid pages.xml file.

Yes, I don't know why we aren't validating .xml against the schema (Norman does I think). You could open an issue about this.

Anyways, these are the ones that I've had a chance to play with so there could be others. I hope this doesn't come off as trolling, intonation gets lost in forum posts and so I just wanted to be clear that I'm not writing this out of anger but rather enthusiasm about this framework and particularly understanding the pages.xsd document and being able to use it correctly. One thing that I've been really trying to avoid is potentially filing out a bug report when in fact it's simply user error ... that would be embarrassing. Anyways, if need be I will file a JIRA report. Let me know ...

Please use JIRA for this, it's the right forum as it includes notification, tracking, release note generation etc. The worst that happens is we reject your issue, and if you report an issue clearly like above that won't happen!

And thanks for your help - this attention to detail is really important!

 

Read about how to report a bug.
05. Sep 2008, 18:13 CET | Link
Pete Muir wrote on Sep 05, 2008 13:43:
Yes, I don't know why we aren't validating .xml against the schema (Norman does I think). You could open an issue about this.

https://jira.jboss.org/jira/browse/JBSEAM-2938

 

Check out my weblog or have a look at the books I wrote.

05. Sep 2008, 18:21 CET | Link
Pete Muir wrote on Sep 05, 2008 13:43:
Better still: 
<xs:element name="pages">
        <xs:annotation>
            <xs:documentation>The root of a pages.xml 
              file</xs:documentation>
        </xs:annotation>
        <xs:complexType>
            <xs:choice minOccurs="0" 
              maxOccurs="unbounded">
                <xs:element ref="pages:conversation"/>
                <xs:element ref="pages:page"/>
                <xs:element minOccurs="0"
              maxOccurs="unbounded"
                ref="pages:exception"/>
            </xs:choice>
            <xs:attributeGroup
              ref="pages:attlist.pages"/>
        </xs:complexType>
    </xs:element>
I fixed this.

Actually you can take the minoccurs and maxoccurs out of the pages:exception reference, it's superfluous since the choice is already doing this.

Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.
I don't know XSD well enough to fix this. The rule we need is any order, end-conversation is optional, and must have either http-error OR redirect

I've been using XSD for a few years now so I can change this for you if you'd like.

  • both http-error and redirect allow many messages, schema reports to only allow zero or one
Only the first one will be used

Validation at startup will take care of this.

  • redirect view-id attribute should be of type IDREF or xs:keyref, don't want to point to a page that doesn't exist right?
That's fine, Seam supports virtual pages, and also pages that aren't specified in pages.xml

Good point. In that case IDREF or xs:keyref would be inappropriate.

  • http-error error-code attribute should be required(?)
Agreed. I fixed this.
2.) Using Regex to clarify allowable values The use of regex would greatly help narrow what a user (us app developers). For example, the view-id attribute of the page element accepts ... a view id. Why not restrict it like this: 
<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern value="/.*"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>
Ok, I applied: 
<xs:simpleType name="view-id">
        <xs:restriction base="xs:string">
            <xs:pattern value="(/.*)|\*"/>
        </xs:restriction>
    </xs:simpleType>
which seems correct to me
If one wanted, a narrowing of scope could further the selection to something like: 
<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern value="/.*\..*"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>
Or even: 
<xs:attribute name="view-id">
  <xs:simpleType name="view-id">
      <xs:restriction base="xsd:NMTOKEN">
          <xs:pattern
          value="/.*\.(\.seam|\.html|\.xhtml|.\jsp)"/>
      </xs:restriction>
  </xs:simpleType>
</xs:attribute>
But that would probably be too restrictive (someone might complain that they can't create a page called index.monkey)
Neither of these are valid, there is no requirement a view id must end in .*

Ah yes, you're right. The starting slash is about the only thing you can restrict.

  • Restrict page element's conversation attribute to being token
I don't think this will work, as conversations can be declared in another pages.xml file.

xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.

  • scheme to being either http or https
File an issue for this, I need to think about it.

Done, it's here:

3387

3.) Schema Annotation/Documentation Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.
Totally agreeed. Want to write a patch with what you know/can garner from the docs? We need these for all the components.xsd as well...

Sure, I can do that as well as the changes suggested above (where order doesn't matter). Can you point me to the latest pages.xsd on SVN so I can grab the most recent? That way updating won't be too much of a headache. At which point I can either email you or post here(?) the updates.

This sort of check really should be performed at the beginning of the startup procedure and belch validation exceptions if the user has not provided a valid pages.xml file.
Yes, I don't know why we aren't validating .xml against the schema (Norman does I think). You could open an issue about this.

Done. Made it a feature request since I don't think it's considered a bug. Found here: 3388

Anyways, these are the ones that I've had a chance to play with so there could be others. I hope this doesn't come off as trolling, intonation gets lost in forum posts and so I just wanted to be clear that I'm not writing this out of anger but rather enthusiasm about this framework and particularly understanding the pages.xsd document and being able to use it correctly. One thing that I've been really trying to avoid is potentially filing out a bug report when in fact it's simply user error ... that would be embarrassing. Anyways, if need be I will file a JIRA report. Let me know ...
Please use JIRA for this, it's the right forum as it includes notification, tracking, release note generation etc. The worst that happens is we reject your issue, and if you report an issue clearly like above that won't happen! And thanks for your help - this attention to detail is really important!

You're welcome. Just checking. :)

 

Beware of programmers carrying screwdrivers
05. Sep 2008, 19:51 CET | Link
Arron Ferguson wrote on Sep 05, 2008 18:21:
Actually you can take the minoccurs and maxoccurs out of the pages:exception reference, it's superfluous since the choice is already doing this.

Done.

Same issue with the exception element ... the end-conversation element having to be at the beginning is not being enforced. I'm assuming that this should be enforced.
I don't know XSD well enough to fix this. The rule we need is any order, end-conversation is optional, and must have either http-error OR redirect
I've been using XSD for a few years now so I can change this for you if you'd like.

Please - just attach a unified diff to JIRA :-)

  • Restrict page element's conversation attribute to being token
I don't think this will work, as conversations can be declared in another pages.xml file.
xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.

I don't understand how these comments are related..??

3.) Schema Annotation/Documentation Although the new 2.1 pages xsd has been fleshed out a bit more (and even annotation and documentation elements are included now), there is minimal documentation inside of this schema. Simply stating the obvious (e.g., 'Page action' for the action element) doesn't help app developers fully understand the intentions of particular elements. Fleshing the xsd schema out more will also help (you) the framework developers in solidifying the contract each element has with API calls possibly written by someone else.
Totally agreeed. Want to write a patch with what you know/can garner from the docs? We need these for all the components.xsd as well...
Sure, I can do that as well as the changes suggested above (where order doesn't matter). Can you point me to the latest pages.xsd on SVN so I can grab the most recent? That way updating won't be too much of a headache. At which point I can either email you or post here(?) the updates.

https://svn.jboss.org/repos/seam/trunk/src/main/org/jboss/seam/ - just use trunk. Post a patch in JIRA in unified diff format.

 

Read about how to report a bug.
05. Sep 2008, 22:09 CET | Link
Pete Muir wrote on Sep 05, 2008 19:51:
  • Restrict page element's conversation attribute to being token
xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.
I don't understand how these comments are related..??

If I understand correctly you were concerned with xs:token being used for conversation attribute type. I was saying that xs:token simply collapses whitespace down to a single white space (I suppose you could further restrict if you wanted). Maybe I misunderstood what you meant.

https://svn.jboss.org/repos/seam/trunk/src/main/org/jboss/seam/ - just use trunk. Post a patch in JIRA in unified diff format.

Sure, gotcha. I'll do that. May take a few days though.

Regards,

Arron

 

Beware of programmers carrying screwdrivers
06. Sep 2008, 00:00 CET | Link
Arron Ferguson wrote on Sep 05, 2008 22:09:
Pete Muir wrote on Sep 05, 2008 19:51:
  • Restrict page element's conversation attribute to being token
xs:token collapses whitespace (i.e., all whitespace replaced with single spaces, trailing spaces have been removed. But if this may be an issue, leaving it is okay too.
I don't understand how these comments are related..??
If I understand correctly you were concerned with xs:token being used for conversation attribute type. I was saying that xs:token simply collapses whitespace down to a single white space (I suppose you could further restrict if you wanted). Maybe I misunderstood what you meant.

No, I think I misunderstood how xs:token works. File a JIRA issue, we can check it out :)

 

Read about how to report a bug.
06. Sep 2008, 00:13 CET | Link
Pete Muir wrote on Sep 05, 2008 19:51:
https://svn.jboss.org/repos/seam/trunk/src/main/org/jboss/seam/ - just use trunk. Post a patch in JIRA in unified diff format.

Authorization required :(

 

Beware of programmers carrying screwdrivers
05. Sep 2008, 18:24 CET | Link

Whoa, that was fast ... you beat me to the punch. :)

Mine is at: https://jira.jboss.org/jira/browse/JBSEAM-3388

Sound similar but if mine's a duplicate, close mine.

 

Beware of programmers carrying screwdrivers
12. Sep 2008, 06:47 CET | Link

I've filed the following at JIRA:

https://jira.jboss.org/jira/browse/JBSEAM-3414

 

Beware of programmers carrying screwdrivers