Invalid DOCTYPE instruction in example SQL Map file in documentation bundle.
----------------------------------------------------------------------------
Key: IBATIS-258
URL: http://issues.apache.org/jira/browse/IBATIS-258
Project: iBatis for Java
Type: Bug
Components: Documentation
Versions: 2.1.7
Reporter: Mark Tye
Priority: Minor
The user and developer Javadoc bundles (user-javadoc.zip and dev-javadoc.zip)
both contain an example SQL Map File named sql-map.txt, located at
/com/ibatis/sqlmap/client, that is referenced in the API documentation.
(Specifically, the class-level Javadoc for the
com.ibatis.sqlmap.client.SqlMapClientBuilder links to sql-map.txt with an
anchor titled "An SQL Map File".)
This sql-map.txt file contains an error. Lines 2 through 4 of the file contain
a DOCTYPE instruction for the sqlMap element that references the DTD located at
"http://www.ibatis.com/dtd/sql-map-2.dtd";. Unfortunately, the unique PUBLIC
name associated with this DTD is incorrect. The PUBLIC name specified in the
DOCTYPE instruction is:
"-//iBATIS.com//DTD SQL Map Config 2.0//EN"
However, that unique name is associated with the SQL Map *Config* DTD, not with
the SQL Map DTD. I believe the correct name that should be used is:
""-//iBATIS.com//DTD SQL Map 2.0//EN"
The usage of the same unique name for two different DTDs causes problems for
certain validating parsers. (Crimson, in particular.) When a SQL Map Config is
parsed, the SQL Map Config DTD is associated with the unique name specified in
the DOCTYPE instruction. When the same parser subsequently tries to validate a
SQL Map that uses the same unique name, it applies the SQL Map Config DTD to
the SQL Map file. This results in a validation error, because the SQL Map
Config DTD declares that the sqlMap element must be EMPTY, even though the SQL
Map DTD allows nested content.
The error in the sql-map.txt file causes problems for developers who use the
file as a template to configure their own SQL Maps. If they don't notice the
very subtle error in the DOCTYPE instruction, their attempts to build a
SqlMapClient will result in cryptic SAXParseExceptions that contain no hint as
to what the underlying problem is.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see:
http://www.atlassian.com/software/jira
