Edit D:\app\Administrator\product\11.2.0\dbhome_1\ide\src\javax\ide\model\java\declaration\package.html

<body>

<hr>

Declaration model.

<h2> Similarities to reflection </h2>

<h3> Method names </h3>

This package's method names should match method names in reflection as
closely as possible. This allows callers who are already familiar with
reflection API to learn this API quicker. Examples: <code>
ClassD#getEnclosingMethod()</code>, <code>
ClassD#getInterfaces()</code>, <code>
GenericD#getTypeParameters()</code>.

<h2> Differences from reflection </h2>

<h3> No special <code>getGeneric*()</code> methods </h3>

Consider, for example, <code> java.lang.reflect.Method#getReturnType()
Method.getReturnType() </code>. Though the return type of a method is a
generic type, <code>getReturnType()</code> must return the type
erasure of the return type for compatibility with callers compiled
against the jdk < 1.5 reflection API. Thus, in order to get the real
return type of a method in the jdk >= 1.5 reflection API, callers must
call <code> java.lang.reflect.Method#getGenericReturnType()
Method.getGenericReturnType() </code>. <p/>

This API is not bound by said requirement and is free to return the
real return type of a method, generic or not. This trims down the size
of the API and improves the readability of caller code that operates
upon the real return type instead of the return type's erasure. We
argue that the set of callers operating on the real return type form
the majority. There is no loss of functionality because callers who
want the type erasure can call
<code>getReturnType().getTypeErasure()</code>. <p/>

<h3> Non-empty TypeD </h3>

The jdk >= 1.5 reflection API requires that a caller casts a Type to
be a Class (or other subtype) before calling methods such as
<code>getMethods()</code> and <code>isAssignableFrom(C)</code>. While
technically correct, it is a very clunky API for IDE features to
use. Because many of said operations are performed regardless of
whether the target type is a class, type variable, wildcard type,
array type, etc., these have been pushed into the supertype <code>
TypeD</code>. <p/>

Here are some notable additions above what <code> java.lang.Class</code>
provides: <p/>

<ul>

<li> <code>getHierarchy()</code>. Returns a type's list of base
classes and a base interfaces without duplicates. Used variously by
refactoring and browsing IDE features. <p/>

<li> <code>getTypeErasure()</code>. Ensures that there is no loss of
functionality with the removal of <code>getGeneric*()</code>
methods. See above discussion.

</ul>

<h3> The hidden <code>clinit</code> method </h3>

Though the reflection API does not provide access to the hidden
<code>clinit</code> method, certain IDE features need access to it.
In particular, debugging features require access to the method's line
number table for determining if a breakpoint may be set on a
particular line of code. <p/>

<h3> <code>getName()</code> returns simple names </h3>

All implementations of <code> HasNameD#getName()</code> should return
simple names. The only place this deviates from the reflection API is
that <code> ClassD#getName()</code> returns its simple name instead of
<code> java.lang.Class#getName()</code> which returns a fully
qualified class name or a FieldDescriptor name. <p/>

The benefit is that the name returned by <code> ClassD#getName()</code>
conforms strictly to the JLS whereas the name returned by <code>
java.lang.Class#getName()</code> conforms neither to the JLS nor the JVMS.
To get the fully qualified source name of a class, use <code>
TypeD#getSourceName()</code>, conformant to the JLS3. To get the fully
qualified type descriptor of a class, use <code>
TypeD#getTypeDescriptor()</code>, conformant to the JVMS3. <p/>

<h3> <code>getCanonicalName()</code>? </h3>

We use the method <code> TypeD#getSourceName()</code> instead of <code>
java.lang.Class#getCanonicalName()</code>. The two problems posed by
<code>getCanonicalName()</code> is that it is only valid on raw types
and that JLS3 isn't out yet which means no one actually knows what
"canonical name" means. The use of the term "source name" is both more
readable and more general. It applies equally well to parameterized
types, type variables, and wildcard types. <p/>

<h3> Never return a <code>null</code> String </h3>

A String typed method should NEVER return null if the specified value
is not present. A String typed method may only return null if the
method call itself is irrelevant. An example of where the reflection
API returns a null String is <code> java.lang.Package#getName()</code>
for the root package. Returning the empty string for the root package
allows callers to fill a Map with <code> PackageD</code> values and
<code> PackageD#getSourceName()</code> keys.

However, it is unclear what to return for String typed methods where
the result is irrelevant. Consider <code> TypeD#getSourceName()</code>
for anonymous inner classes. An anonymous class may not be referred to
in a source compilation unit, rendering the call to
<code>getSourceName()</code> irrelevant. Returning <code>null</code>
poses a problem preventing callers from filling a Map with <code>
TypeD</code> values and the <code> TypeD#getSourceName()</code>
keys. Special case handling decreases code readibility. However,
returning the empty string also poses a problem because then two
anonymous classes will share the same key. <p/>

We choose to return the empty string in this case with this reasoning.
Consider that <code> TypeD#getSourceName()</code> uniquely identifies a type
in a specific scope. That is, suppose there is a type variable
<code>T</code> and a local class <code>T</code> both accessible at a
given point in a source compilation unit. (Yes, that will generate a
compile error but unlike the reflection API, this API must be able to
handle erroneous compilation units.) However, one type will always
hide the other, therefore it is safe to keep a Map of visible TypeD's
at a given point in a source compilation unit. A refactoring feature,
say, may want to be able to insert the value of
<code>getSourceName()</code> into that given point in the source.  If
<code>getSourceName()</code> returns the empty string, then the caller
will simple insert nothing into the buffer. <p/>

</body>

Ms-Dos/Windows Unix Write backup

jsp File Browser version 1.2 by www.vonloesch.de