Internal packages of xerces

[Dave Brosius <db...@mebigfatguy.com>]

Hi folks,

    Could someone tell me what packages of the xerces J2 source tree are 
considered off limits to client developers?

I see in the standard api, that

org.apache.xerces

is not mentioned, so i'd assume any use of classes in package that starts 
with that is a mistake.

However, I see that

org.apache.xerces.xni

is probably ok to use.

So is there an official use this/don't use this answer with regards to 
xerces packages?

thanks,
dave 


---------------------------------------------------------------------
To unsubscribe, e-mail: j-users-unsubscribe@xerces.apache.org
For additional commands, e-mail: j-users-help@xerces.apache.org

Re: Internal packages of xerces

[Michael Glavassevich <mr...@ca.ibm.com>]

Hi Dave,

"Dave Brosius" <db...@mebigfatguy.com> wrote on 02/21/2009 12:17:13 AM:

> Hi folks,
>
>     Could someone tell me what packages of the xerces J2 source tree are
> considered off limits to client developers?

I wouldn't go so far as to say that they're off limits, just that it's
usually unwise to write code which uses internals and should avoid doing
that if you can. I recommend against it unless you have some special need
which isn't met by the standard APIs, Xerces' public APIs, features and
properties or even the Java class library (e.g. java.util.regex vs.
org.apache.xerces.impl.xpath.regex) and understand that your code may break
at any time in the future if you code to internals. 99% of users should
never have a need to do this.

> I see in the standard api, that
>
> org.apache.xerces
>
> is not mentioned, so i'd assume any use of classes in package that starts

> with that is a mistake.
>
> However, I see that
>
> org.apache.xerces.xni
>
> is probably ok to use.

Yes, XNI is a public API. So is the XML Schema API. Plus a handful of other
classes/packages (e.g. util).

> So is there an official use this/don't use this answer with regards to
> xerces packages?

Classes which are internal are marked with @xerces.internal in the source.
This expands to a warning in the Javadoc: "INTERNAL: Usage of this class is
not supported. It may be altered or removed at any time." Those are the
ones that you should generally avoid.

> thanks,
> dave
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: j-users-unsubscribe@xerces.apache.org
> For additional commands, e-mail: j-users-help@xerces.apache.org

Thanks.

Michael Glavassevich
XML Parser Development
IBM Toronto Lab
E-mail: mrglavas@ca.ibm.com
E-mail: mrglavas@apache.org