This class represents a resource on an SMB network. Mainly these
resources are files and directories however an
SmbFile
may also refer to servers and workgroups. If the resource is a file or
directory the methods of
SmbFile
follow the behavior of
the well known
java.io.File class. One fundamental difference
is the usage of a URL scheme [1] to specify the target file or
directory. SmbFile URLs have the following syntax:
smb://[[[domain;]username[:password]@]server[:port]/[[share/[dir/]file]]][?param=value[param2=value2[...]]]
This example:
smb://storage15/public/foo.txt
would reference the file
foo.txt
in the share
public
on the server
storage15
. In addition
to referencing files and directories, jCIFS can also address servers,
and workgroups.
Important: all SMB URLs that represent
workgroups, servers, shares, or directories require a trailing slash '/'.
When using the java.net.URL class with
'smb://' URLs it is necessary to first call the static
jcifs.Config.registerSmbURLHandler(); method. This is required
to register the SMB protocol handler.
The userinfo component of the SMB URL (domain;user:pass) must
be URL encoded if it contains reserved characters. According to RFC 2396
these characters are non US-ASCII characters and most meta characters
however jCIFS will work correctly with anything but '@' which is used
to delimit the userinfo component from the server and '%' which is the
URL escape character itself.
The server
component may a traditional NetBIOS name, a DNS name, or IP
address. These name resolution mechanisms and their resolution order
can be changed (See Setting Name
Resolution Properties). The servername and path components are
not case sensitive but the domain, username, and password components
are. It is also likely that properties must be specified for jcifs
to function (See Setting
JCIFS Properties). Here are some examples of SMB URLs with brief
descriptions of what they do:
[1] This URL scheme is based largely on the SMB
Filesharing URL Scheme IETF draft.
SMB URL Examples |
URL | Description |
smb://users-nyc;miallen:mypass@angus/tmp/ |
This URL references a share called tmp on the server
angus as user miallen who's password is
mypass .
|
smb://Administrator:P%40ss@msmith1/c/WINDOWS/Desktop/foo.txt |
A relativly sophisticated example that references a file
msmith1 's desktop as user Administrator . Notice the '@' is URL encoded with the '%40' hexcode escape.
|
smb://angus/ |
This references only a server. The behavior of some methods is different
in this context(e.g. you cannot delete a server) however
as you might expect the list method will list the available
shares on this server.
|
smb://myworkgroup/ |
This syntactically is identical to the above example. However if
myworkgroup happends to be a workgroup(which is indeed
suggested by the name) the list method will return
a list of servers that have registered themselves as members of
myworkgroup .
|
smb:// |
Just as smb://server/ lists shares and
smb://workgroup/ lists servers, the smb://
URL lists all available workgroups on a netbios LAN. Again,
in this context many methods are not valid and return default
values(e.g. isHidden will always return false).
|
smb://angus.foo.net/d/jcifs/pipes.doc |
The server name may also be a DNS name as it is in this example. See
Setting Name Resolution Properties
for details.
|
smb://192.168.1.15/ADMIN$/ |
The server name may also be an IP address. See Setting Name Resolution Properties
for details.
|
smb://domain;username:password@server/share/path/to/file.txt |
A prototypical example that uses all the fields.
|
smb://myworkgroup/angus/ <-- ILLEGAL |
Despite the hierarchial relationship between workgroups, servers, and
filesystems this example is not valid.
|
smb://server/share/path/to/dir <-- ILLEGAL |
URLs that represent workgroups, servers, shares, or directories require a trailing slash '/'.
|
smb://MYGROUP/?SERVER=192.168.10.15 |
SMB URLs support some query string parameters. In this example
the SERVER parameter is used to override the
server name service lookup to contact the server 192.168.10.15
(presumably known to be a master
browser) for the server list in workgroup MYGROUP .
|
A second constructor argument may be specified to augment the URL
for better programmatic control when processing many files under
a common base. This is slightly different from the corresponding
java.io.File
usage; a '/' at the beginning of the second
parameter will still use the server component of the first parameter. The
examples below illustrate the resulting URLs when this second contructor
argument is used.
Examples Of SMB URLs When Augmented With A Second Constructor Parameter |
First Parameter | Second Parameter | Result |
smb://host/share/a/b/
|
c/d/
|
smb://host/share/a/b/c/d/
|
smb://host/share/foo/bar/
|
/share2/zig/zag
|
smb://host/share2/zig/zag
|
smb://host/share/foo/bar/
|
../zip/
|
smb://host/share/foo/zip/
|
smb://host/share/zig/zag
|
smb://foo/bar/
|
smb://foo/bar/
|
smb://host/share/foo/
|
../.././.././../foo/
|
smb://host/foo/
|
smb://host/share/zig/zag
|
/
|
smb://host/
|
smb://server/
|
../
|
smb://server/
|
smb://
|
myworkgroup/
|
smb://myworkgroup/
|
smb://myworkgroup/
|
angus/
|
smb://myworkgroup/angus/ <-- ILLEGAL (But if you first create an SmbFile with 'smb://workgroup/' and use and use it as the first parameter to a constructor that accepts it with a second String parameter jCIFS will factor out the 'workgroup'.)
|
Instances of the SmbFile
class are immutable; that is,
once created, the abstract pathname represented by an SmbFile object
will never change.