The JNIPort framework
_____________________

JNIPort is a Smalltalk library which allows Java code to be invoked from
Smalltalk. It acts as a bridge between the world of Smalltalk objects
and a Java Virtual Machine (JVM) where Java code is executing. With
JNIPort you can:

    * Supplement Smalltalk's libraries with the rather extensive Java
libraries from Sun and other vendors.

    * Use the normal (to a Smalltalker) interactive way of playing with
objects and code in workspaces to learn about and prototype Java
operations.

    * Continue to use your legacy Java code as you migrate to a more
grown-up language…;-)


You talk to a Java object via a Smalltalk object that acts as a proxy
for it. You can call Java methods via the proxy using a lowish-level API
where you have to tell the proxy what the method name is, what the
argument types are, and so on. Alternatively you can use a higher-level
of wrapper methods that are either statically generated, or created
dynamically.

Java classes are represented explicitly by wrapper objects (called class
statics), so each proxy for a Java instance has both a Smalltalk class
and a reference to the (shared) class static. The Smalltalk class
defines the wrapper methods for calling the Java object's methods, and
accessing its fields. The class static is the single member of a
different Smalltalk class that has methods for using the “static”
methods and fields of the Java class. The class static also has methods
corresponding to the Java class's constructors, so it acts as a factory
for new instances. (That means that from the point of view of a JNIPort
programmer, Java classes really are objects!)

A few warnings before you start to expect too much:

    * JNIPort does not provide complete interoperability between Java
and Smalltalk. For instance it is not possible to create Smalltalk
subclasses of Java classes (or the other way around).

    * The facilities for calling back from Java into Smalltalk are weak,
slow, and clunky.

    * JNIPort allows proper interaction with Java objects but it cannot
magically give you the ability to redefine Java classes interactively
too.

    * Deploying applications based on a mixture of Java and Smalltalk
may be a somewhat challenging. For instance, needed wrapper classes must
not be removed during runtime creation, even when they are not
referenced anywhere in the Smalltalk code.


License
_______

JNIPort was originally written by Chris Uppal for Dolphin Smalltalk and
published under a liberal license which permits its use in commercial
and non-commercial software. 

Joachim Geidel has ported JNIPort to VisualWorks. The portions written 
by Joachim Geidel are available under the MIT license. 

Portions of this software created by Joachim Geidel are (c) 2006-2009 
Joachim Geidel. These portions fall under the "MIT license":

"Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE."

Portions of this software created by Chris Uppal are (c) Chris Uppal,
2001-2007. These portions are covered by Chris Uppal's license:

"The terms under which you may use this software are:
	You must not claim that you wrote it.
	You must not claim that you own it.
	You use it at your own risk.

I'd appreciate it if you didn't distribute modified versions without 
at least trying to tell me about the changes you thought worthwhile.

	-- chris"


Documentation
_____________

Chris Uppal's documentation for JNIPort for Dolphin is contained in the
archive JNIPort_Docs.zip.

Additional documentation, in particular for the VisualWorks version,
is available online at 

	http://jniport.wikispaces.com


Components
__________

To use JNIPort, you need:
	- the parcel Registry distributed with VisualWorks,
	- the parcel FastCMethodPointers,
	- the parcel WeakCollections,
	- the parcel JNIPort VW75 Extensions (only in in VisualWorks 7.5 
	  or earlier),
	- the parcel JNIPort VW76 Extensions (only in in VisualWorks 7.6),
	- the parcel JNIPort Prerequisites,
	- the parcel JNIPort.

Some rudimentary development tools are contained in the parcel JNIPort Tools.

To run the unit tests for JNIPort, load the parcel JNIPort Tests. You also 
need additional files from the archive JNIPort_Extras.zip. For
additional instructions read the bundle comment of JNIPort Tests.

Updates may be available in Cincom's Public Store Repository. See

	http://www.cincomsmalltalk.com/CincomSmalltalkWiki/PostgreSQL+Access+Page
	
for instructions about how to access the public repository.