[jcifs] jcifs-0.6b released

[Michael B.Allen]

jcifs-0.6b released

This is the first beta of 0.6.

There have been significant changes under the hood. The primitives such
as packet encoding/decoding and transport have proven very sturdy however
the top level glue and logic driving the client really needed an overhaul
in hindsight. The client is much smarter now whereas previously jCIFS was
quite chatty and used some messages abusively (NodeStatusRequest). Some
other cleanups that took into account allocation of buffers and
large numbers of objects have resulted in measureable performance
improvements. All of this should be transparent to the user however my
confidence in the stabilty of 0.5.1 no longer applies. It will take some
time to confirm everything works as advertised. I am confident however
that any bugs will only require minor adjustments to fix. Of course the
name resolution bug that triggered this crusade has been fixed.

There are some API changes. Most methods of SmbFile throw the now public
SmbException. Natrually, this will require changes to existing code. For
example, if your code was:

if( r.delete() ) {
  System.out.println( "delete successfull" );
} else {
  System.out.println( "error!" );
}

you might replace this with:

try {
  f.delete();
  System.out.println( "delete successfull" );
} catch( SmbException se ) {
  System.out.println( "error: " + se.getMessage() );
}

There are quite a few different messages that can be provoked such as:

The file is being used by another process
The device is not ready
All pipe instances are busy
...

not all of which have text messages (and which ones do have messages are
in only English at the moment). You can test and make dicisions based on
the errorClass and errorCode of an SmbException. All SmbExceptions are
thrown through these methods unless an object implementing the AuthHandler
interface has been called with the static SmbFile.setAuthHanler method. If
an AuthHandler has been specified the following authentication related
SmbExceptions:

Access denied
Bad password
The client does not have the necessary access rights for the
  requested function
The user account has expired
The user is not allowed to access this server from this client
The user is not permitted to access the server at this time
The password of the user has expired

will not be thrown by SmbFile methods but rather passed in the AuthInfo
object to the AuthHandler's authenticate() method along with the username,
password, domain, and target URL if one of these SmbExceptions occurs. See
http://lists.samba.org/pipermail/jcifs/2001-October/001553.html for a
related discussion. I believe this is a powerfull feature in itself. This
provides for sophisticated error handling and consistent error messages
(the messages are the same as those reported by Windows clients). There
is also an oppurunity to introduce a ResourceBundle of text messages
here. I beleive it will work quite well and in practice I do not believe
code will be cluttered with try/catch.

The NbtAddress class was designed to handle NetBIOS name queries
similarly to the common InetAddress class. Unfortunately a lapse in
judgment integrated DNS queries into this class in jcifs-0.5 (thus the
name service bug). The solution is to remove this DNS code and provide
a wrapper class that handles both DNS queries as well as NetBIOS queries
mainly delegating the work to InetAddress and NbtAddress. This class is
UniAddress. Here is how each of these classes should be used:

o InetAddress - Lookup a DNS name
o NbtAddress - Lookup a NetBIOS name or perform NetBIOS specific
    queries (NodeStatus with getAllByAddress)
o UniAddress - Don't know or care what type of name it is, try to
    find the name with both DNS and NetBIOS queries if necessary. Query
    behavior is governed by the jcifs.resolveOrder property.

So generally the UniAddress class should be used if you wish to interface
with name services directly (normally not necessary when working with
the jcifs.smb package).

In summary the classes that have been added or made public are:

jcifs.UniAddress
jcifs.util.AuthHandler
jcifs.util.AuthInfo
jcifs.smb.SmbException