Name: dhT79914 Date: 11/11/99



See bugtraq RFE# 4281429

1. Introduction
   1.1. Project/Component Working Name:

Native drawing JAWT interface improvements

   1.2. Name of Document Author/Supplier:

David Herron, AWT SQE (Test development)

   1.3. Date of This Document:

Oct 14, 1999

   1.4. Name of Major Document Customer(s)/Consumer(s):

David Herron, AWT SQE (Test development)

2. Project Summary
   2.1. Project Description

The new native drawing support in the Kestrel (1.3) release
is a welcome addition and will likely see use in the market.

This feature works as advertised, however there is an
area of difficulty that the programmer has in coding
the native side of the component. The problem has to do with
management of allocation of various native resources. The
AWT implementation already has methods in its native implementation
to manage these resources, but access to those methods is not
available to one programming to the JAWT interface. This means,
then, that the programmer must separately manage allocation of
those same resources.

For example: On the X side the resources of concern are color
map allocations (on 256 color X Visuals), font mapping, and
graphics context (GC) allocation/deallocation. Other platforms
will have similar global resources whose allocation is supposed
to be carefully monitored by the application.

The project proposal is to extend the native JAWT structures to
have additional methods. The extension must be on a per platform
basis since both the specific resources to coordinate, and the
data types to use, are unique to each platform.

For example, (on X) in setting a color value in a GC to draw
in the desired color, one calls XSetForeground (or XSetBackground)
with a "long". The value this "long" takes varies depending
on the Visual being used, and the method to calculate this
value varies also on the Visual being used. It can be complex
to determine the way to calculate this value, especially in cases
where a small (256 cell) color map is being used. In the color map
case, AWT is already maintaining a table of color allocations
and it would be a performance boost (fewer round trips to the
X server) if the native JAWT supported code could call the AWT code
which manages that table. The total interface needs are to
provide red/green/blue (and perhaps alpha) values, and receive back
a "long" which can then be given to XSetFore/Background by
the programmer.

An example of how jawt_md.h might look is (on the X platform):

typedef struct jawt_X11DrawingSurfaceInfo {
Drawable drawable;
Display* display;
VisualID visualID;
Colormap colormapID;
int depth;

long (JNICALL *GetColorValue) (JNIEnv *env,int red, int green, int blue);
XFontStruct * (JNICALL *FindXFont) (JNIEnv *env, jobject font);
GC (JNICALL *GetGC) (JNIEnv *env);
void (JNICALL *FreeGC) (JNIEnv *env, GC gc);
} JAWT_X11DrawingSurfaceInfo;

Each of these maps pretty directly to AWT internal methods.

   2.2. Risks and Assumptions

The original JAWT project did not include this kind of support
presumably because of the focus - allowing programmers to incorporate
pre-existing native drawing libraries into a Java app.

As we designed JAWT tests, one aspect we looked at was the usability
of this interface. In other words, were there any "pain points"
in coding native drawing using this interface. This issue, of
native resource allocation, is the only such limitation we found.

However our project, since it was creating new code specifically
for testing this interface, is different from the expected use
of JAWT. Instead of having pre-existing code (which likely
already has code to manage these resources) we were starting from
scratch.

Looking at it from another standpoint there is another consideration.
The hypothetical assumed use, to incorporate an existing set of
native code, still must have that code cooperating with Java/AWT
in managing these resources. There is potential confusion in the
allocation with two code modules trying to manage the same information.
In addition there are performance benefits if the native code
module were able to call the AWT internal methods. A color lookup
might, for example, often be satisfied without going to the operating
system or X server to satisfy the color request.

It is important in this project to keep it small and focused.

3. Business Summary
   3.1. Problem Area

As I said above - resource management for resources that AWT already
has methods to manage.

   3.2. Market/Requester

AWT SQE

   3.3. Business Justification

Ease of customers in using the native drawing feature.

   3.4. Competitive Analysis

er...??

   3.5. Opportunity Window/Exposure

Given the time frame (we've just entered code freeze for Kestrel)
it is not opportune to make this extension for Kestrel. It may
be appropriate for 1.3.1, and is certainly appropriate for 1.4.

4. Technical Description

I gave most of this above.

There is existing methods in the native side of AWT to handle
these resource requests. One would simply create a linkage method
interfacing from JAWT to these existing methods. In some cases you
will find the existing internal methods are not quite having the
right interface for use from JAWT, but it should be simple enough
to slightly shuffle the internal methods so that they are usable
from both JAWT and existing AWT code.

5. Reference Documents

Unknown - there is a tutorial for native drawing on the javasoft
web site.


6. Resources and Schedule
   6.1. Projected Availability

Preferably 1.3.1

   6.2. Cost of Effort

per platform:
1-2 days for needs analysis (basically, review the existing
existing AWT implementation, and choose those resources
resources which have extensive code to support their
allocation)
1-2 days for implementation of jawt_md.h extension and the
linkage functions.

   6.3. Cost of Capital Resources

1 programmer, one week

7. Prototype Availability
   7.1. Prototype Availability

Not needed

   7.2. Prototype Cost

Not needed


======================================================================