[ve-dev] org.eclipse.jem API

[Rich Kulp <richkulp@xxxxxxxxxx>]

Hi,

First to Chuck Bridgham and David
Williams, could you please pass this on to your clients (WTP, etc.)
to see if this will be a problem for them?

And now the request: We will be slowly
moving parts of org.eclipse.jem to API. Parts of it are already API.

Already API:

• The Java EMF Model Interfaces themselves (such as org.eclipse.jem.java.JavaClass, Field, etc.)
• org.eclipse.jem.util Utilities
• org.eclipse.jem.workbench Utilities

What I would like to do now is to clarify
one part of the API. That is the Java EMF Model implementation classes,
(e.g. org.eclipse.jem.java.impl.JavaClassImpl). I would like to
make it clear that the implementation classes are not API. They are not
meant to be cast to, nor subclassed. To do this I want to rename the package
to org.eclipse.jem.java.internal.impl. There shouldn't be any users
of the impl classes anyway. If there are, then there will be compile errors,
and they should be fixed. 

There is one more thing with the Java
EMF classes, the NameSpace Prefix contains internal in it. It shouldn't.
For example, an XMI file could have:

<?xml version="1.0" encoding="ASCII"?>
<change:ChangeDescription xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:org.eclipse.jem.internal.java="...
  
The prefix in the code package will
be changed to "org.eclipse.jem.java". This is a non-breaking
change. Old xmi files that are using the old prefix will continue to work
fine with no change. Any new serialized xmi files will have the new prefix
in it.


In addition, I would like turn on the
standard warnings for access to the current true internals in org.eclipse.jem
plugins. These are the compiler warnings that Eclipse can give when accessing
internal packages. The other internals, such as BeanInfo, will not yet
have warnings turned on because they are still being evaluated as to which
should be internals and which should be API.

The packages I intend to turn internal
warnings on are:

• org.eclipse.jem.internal.core
• org.eclipse.jem.internal.java.adapters
• org.eclipse.jem.internal.java.adapters.jdk
• org.eclipse.jem.internal.java.adapters.nls
• org.eclipse.jem.java.internal.impl  - (The renamed Java EMF implementation package)
• org.eclipse.jem.internal.util.emf.workbench
• org.eclipse.jem.internal.util.emf.workbench.nls
• org.eclipse.jem.internal.util.emf.workbench.nature
• org.eclipse.jem.internal.adapters.jdom
• org.eclipse.jem.intenal.plugin

Note:  I have noted one
internals usage that seems to be common. It is to get the ReadAdapter
and call getReflectionSource() or hasReflectionSource() on
it. ReadAdapter has always been internal and is not being renamed here.
But when I turn on compiler warnings, this will show up for people. If
anyone is using these, they should instead use the isExistingType()
and getReflectionType() methods on JavaClass (the API interface)
instead.

If there are any other internal usages
that someone is using, they need to let us know about it so that we can
decide if it should be made API, or if is there an alternative to it.

This would be going into the JEM
1.2.0.0 release (Eclipse 3.2). The JEM 1.1.x.x release will
continue to have the old style.

If there are any comments please let
me know.

Thanks,
Rich Kulp