VWRowsetLibraryInProject

Including the Rowset RI classes in a Visualweb Project

DRAFT

Author: DavidVanCouvering

Visualweb uses JDBC RowSets. We have our own implementation of CachedRowSet. This implementation depends upon the reference implementation (RI) for rowsets.

The Rowset RI is included in the JRE for Java 5 and greater. But it is not included in older JREs.

This means that the Rowset RI is required for visualweb projects deployed to servers running in a 1.4 VM. It is also required if the visualweb project is being built with a 1.4 JDK or earlier.

In the past we have solved this by including rowset.jar, the rowset RI, in NetBeans, and it is added as a library to visualweb projects.

The problem is the Rowset RI is not under an open source license, so it can not be distributed with NetBeans 6.

This page describes the user interface and underlying design for how we are going to handle this.

[[{TableOfContentsTitle=TableOfContents} | {TableOfContents title='Table of Contents'}]]

Overall Goal

The overall goal is to limit as much as possible the inconvenience caused to the user because rowset.jar is not included in NetBeans. Inconvenience can come in two forms:

  • The user doesn't need rowset.jar but is forced to get it
  • The user needs rowset.jar but doesn't know this, and gets unexplained and confusing errors

Make RI available on the Update Center

rowset.jar is currently checked into cvs under
visualweb/ravelibs/rowset
. We will wrap this jar file in an NBM and make it available on the update center

Compile/Design Time: Detect when the user is building with a 1.4 JDK

The user can add a 1.4 JDK as a Java platform using the Java Platform Manager, and they can make it the deafult Java platform.

We need to detect when the user has a VW project configured to us a 1.4 JDK or earlier.

  • When the VW project is created, check to see what Java platform is. If it is 1.4 or earlier, raise an error and guide the user to download and install the rowset NBM:
-----------------------------------------------------------
| The RowSet Reference Implementation (RI) is required     |
| for Java platforms 1.4 or earlier.  Please either        |
| change your Java platform or install the RI from         |
| the Update Center                                        |
|                                                          |
| [[ChangeJavaPlatform | Change Java Platform]]  [GetTheRIFromUpdateCenter]  |
------------------------------------------------------------
  • When the user changes the Java Platform to JDK 1.4 or earlier for a VW project, we need to detect this and raise an error
-----------------------------------------------------------
| The RowSet Reference Implementation (RI) is required     |
| for Java platforms 1.4 or earlier.  If you need 1.4 or   |
| earlier, please install the RI from the Update Center    |
|                                                          |
| [[Cancel | Cancel]]  [GetTheRIFromUpdateCenter]                |
------------------------------------------------------------

Once the NBM is installed, we add it as a compile-time dependency to the project

Sandip comment: Will we be able to add the library reference programatically (which projects it should be added to) or will we have to tell the user to add it using Project:Properties:Libraries dialog?
David comment: I have no idea, I think this question needs to be answered by Po-Ting
Po-Ting comment: Yes, we can add the library reference programatically.

Deployment : Warn user that RI may be needed

When someone builds a WAR file from a VW project, we do not know where they are going to end up deploying it. If they deploy it to a server running in a 1.4 or earlier VM, then their application will fail with a ClassNotFoundException because the RI classes will not be there.

How we handle this needs to take into account what we think is the common case, where the RI is not needed because the server will be running on Java 5 or later.

First of all, if the project is configured to use Java EE 5, then the RI is definitely not needed, because you can not deploy Java EE 5 WAR files to 1.4 or earlier VMs.

If the project's source level is configured to use J2SE 1.4, then we need to warn the user that they need the RI.

We don't want to warn them every time they build, but we should warn them at least once:

-----------------------------------------------------------------
| If you are deploying this application to a server running      |
| on a Java Virtual Machine of version 1.4 or earlier, you       |
| will need to include the JDBC RowSet Reference Implementation  |
| (RI).  You can obtain the RI from the update center and then   |
| it will be added to your application web archive as part       | 
| of building the project.                                       |
|                                                                |
| [[OK | OK]]  [ ] Do not warn me again                                 |
|                                                                |
| [InstallRowSetRIFromUpdateCenter]                         |
-----------------------------------------------------------------

When we install the Rowset NBM, we will add it as a library dependency. Users can remove it as a dependency if they want to through the Project Properties->Libraries dialog

Additional information

  • Bundled file visualweb1/docs/visualweb-rowset-src.zip to allow browsing of rowset source code during debugging
  • rowset.jar license type: BCL only
  • Location of rowset.jar (RowSet RI) in the IDE : to be included in an nbm that gets installed in (visualweb1/modules/ext)
  • Location of RowSet extension jar : modules/org-netbeans-modules-visualweb-libs-rowset.jar

Some History

There are two jar files here:

  • rowset.jar - the RI
  • sqlx.jar - our extensions

rowset.jar

This contains about 30 classes, in packages:

  • java.sql.rowset
  • com.sun.rowset.

It was checked in to our CVS tree in March/04:

date: 2004/03/18 00:51:02;  author: jk145120;  state: Exp;  lines: +278 -278
IN=21937 - check in JDBC_ROWSET_TIGER-1_0-FD-13_Mar_2004 build of rowset and matching src

Since then it has moved around, but has not been changed.

It was delivered with the IDE; e.g., Creator 2u1 (Leopard) had it in rave2.0/core. It is currently in our tree in visualweb/ravelibs/rowset/release/modules/ext.

Some sources were also checked in at the same time, but there's no record that they were ever delivered with the product.

sqlx.jar

This was created shortly after the RI was added. It started out as about four classes (in the reef/hammerhead timeframe), but grew to about a dozen classes in three different packages:

  • com.sun.sql.rowset
  • com.sun.sql.rowset.internal
  • com.sun.sql.rowset.providers

The largest class is CachedRowSetXImpl, which is used for our databinding. This library is currently built from source as part of visualweb, and put into visualweb1/modules/ext.


Issues / Comments

Sandip comment: Should we do this only during build or simply do it as soon as we detect the conditions that require warning?
David comment: So, you mean, as soon as a user chooses J2EE 1.4 as the platform? Sounds good to me
Po-Ting comment: The best time to warm is when creating or opening the project, and change the platform
JohnBaker comment: Need to review, correct items in Additional Information

Lance Andersen comment: This needs to be more specific as WLS and OC4J appservers include a Rowset implementation.
David: I'm not sure how we could handle this. Also, I don't think we have tested with Weblogic and Oracle rowset implementations. I'll raise this on an email thread

Lance Andersen comment: The Issue really is soley surrounding any application, client of server based that needs to use the Sun Rowset Implementation.
David Well, we're specifically addressing a visualweb application, not any application, because in NB, only visualweb requires rowsets to work


Lance Andersen comment: Also, this is soley tied to J2SE/Java SE as a J2EE 1.4 server can be compliant when run using J2SE 5.0.x. David: OK, but since we don't know when they package the WAR file what server under what VM they're going to deploy it to, we have to include the rowset jar file when the user chooses a J2EE 1.4 project. If they choose a Java EE 5 project, then we know rowset.jar is not needed as J2EE 1.5 requires a Java 5 or later VM.

Lance Andersen comment: Also need to check the viability of hosting the Sun RI Rowset jar on netbeans.org I do not believe we discussed this (have to make sure the correct license is there) unless you plan to point them to the download on java.sun.com?
David: What we're hosting is a NetBeans module - it's not sufficient to point them to the download. Are you saying we can't redistribute? I'll send an email and copy Jayashri, who is handling the legal issues of third-party jar files

JimDavidson comment: Re Additional Information: The correct location for RowSet extension jar appears to be:

  • modules/org-netbeans-modules-visualweb-rowset.jar (different filename)

Also, note that this is just a wrapper, that points to the actual jar file, in:

  • modules/ext/sqlx.jar

JohnBaker comment: What is http://www.netbeans.org/source/browse/visualweb/ravelibs/rowset/external/src.zip for and how does it differ from visualweb1/docs/visualweb-rowset-src.zip ?
JimDavidson: Different beasts. src.zip was a file relating to RowSet RI, which has been removed from CVS. visualweb-rowset-src.zip contains the Java sources for our rowset extensions, and is apparently built as part of our build process.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo