Interface SmbResource
-
- All Superinterfaces:
AutoCloseable
- All Known Subinterfaces:
SmbPipeResource
- All Known Implementing Classes:
SmbFile
,SmbNamedPipe
public interface SmbResource extends AutoCloseable
This class represents a resource on an SMB network. Mainly these resources are files and directories however anSmbFile
may also refer to servers and workgroups.- Author:
- mbechler
- See Also:
for the main implementation of this interface
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description boolean
canRead()
Tests to see if the file thisSmbResource
represents can be read.boolean
canWrite()
Tests to see if the file thisSmbResource
represents exists and is not marked read-only.CloseableIterator<SmbResource>
children()
Fetch all childrenCloseableIterator<SmbResource>
children(String wildcard)
Fetch children matching pattern, server-side filteringCloseableIterator<SmbResource>
children(ResourceFilter filter)
CloseableIterator<SmbResource>
children(ResourceNameFilter filter)
void
close()
Close/release the file This releases all resources that this file holds.void
copyTo(SmbResource dest)
This method will copy the file or directory represented by this SmbResource and it's sub-contents to the location specified by the dest parameter.void
createNewFile()
Create a new file but fail if it already exists.long
createTime()
Retrieve the time thisSmbResource
was created.void
delete()
This method will delete the file or directory specified by thisSmbResource
.boolean
exists()
Tests to see if the SMB resource exists.long
fileIndex()
Get the file indexint
getAttributes()
Return the attributes of this file.CIFSContext
getContext()
The context this file was opened withlong
getDiskFreeSpace()
This method returns the free disk space in bytes of the drive this share represents or the drive on which the directory or file resides.SmbResourceLocator
getLocator()
Gets the file locator for this file The file locator provides details aboutString
getName()
Returns the last component of the target URL.SID
getOwnerGroup()
Return the resolved owner group SID for this file or directorySID
getOwnerGroup(boolean resolve)
Return the owner group SID for this file or directorySID
getOwnerUser()
Return the resolved owner user SID for this file or directorySID
getOwnerUser(boolean resolve)
Return the owner user SID for this file or directoryACE[]
getSecurity()
Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory.ACE[]
getSecurity(boolean resolveSids)
Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory.ACE[]
getShareSecurity(boolean resolveSids)
Return an array of Access Control Entry (ACE) objects representing the share permissions on the share exporting this file or directory.int
getType()
Returns type of of object this SmbResource represents.boolean
isDirectory()
Tests to see if the file thisSmbResource
represents is a directory.boolean
isFile()
Tests to see if the file thisSmbResource
represents is not a directory.boolean
isHidden()
Tests to see if the file this SmbResource represents is marked as hidden.long
lastAccess()
Retrieve the last acces time of the file represented by thisSmbResource
long
lastModified()
Retrieve the last time the file represented by thisSmbResource
was modified.long
length()
Returns the length of this SmbResource in bytes.void
mkdir()
Creates a directory with the path specified by thisSmbResource
.void
mkdirs()
Creates a directory with the path specified by this SmbResource and any parent directories that do not exist.InputStream
openInputStream()
Opens an input stream reading the file (read only, sharable)InputStream
openInputStream(int sharing)
Opens an input stream reading the file (read only)InputStream
openInputStream(int flags, int access, int sharing)
Opens an input stream reading the file (read only)OutputStream
openOutputStream()
Opens an output stream writing to the file (truncating, write only, sharable)OutputStream
openOutputStream(boolean append)
Opens an output stream writing to the file (write only, read sharable)OutputStream
openOutputStream(boolean append, int sharing)
Opens an output stream writing to the file (write only, exclusive write access)OutputStream
openOutputStream(boolean append, int openFlags, int access, int sharing)
Opens an output stream writing to the file (write only, exclusive write access)SmbRandomAccess
openRandomAccess(String mode)
Opens the file for random accessSmbRandomAccess
openRandomAccess(String mode, int sharing)
Opens the file for random accessvoid
renameTo(SmbResource dest)
Changes the name of the file thisSmbResource
represents to the name designated by theSmbResource
argument.void
renameTo(SmbResource dest, boolean replace)
Changes the name of the file thisSmbResource
represents to the name designated by theSmbResource
argument.SmbResource
resolve(String name)
Fetch a child resourcevoid
setAttributes(int attrs)
Set the attributes of this file.void
setCreateTime(long time)
Set the create time of the file.void
setFileTimes(long createTime, long lastModified, long lastAccess)
Set the create, last modified and last access time of the file.void
setLastAccess(long time)
Set the last access time of the file.void
setLastModified(long time)
Set the last modified time of the file.void
setReadOnly()
Make this file read-only.void
setReadWrite()
Turn off the read-only attribute of this file.SmbWatchHandle
watch(int filter, boolean recursive)
Creates a directory watch The server will notify the client when there are changes to the directories contents
-
-
-
Method Detail
-
getLocator
SmbResourceLocator getLocator()
Gets the file locator for this file The file locator provides details about- Returns:
- the fileLocator
-
getContext
CIFSContext getContext()
The context this file was opened with- Returns:
- the context associated with this file
-
getName
String getName()
Returns the last component of the target URL. This will effectively be the name of the file or directory represented by thisSmbResource
or in the case of URLs that only specify a server or workgroup, the server or workgroup will be returned. The name of the root URLsmb://
is alsosmb://
. If this SmbResource refers to a workgroup, server, share, or directory, the name will include a trailing slash '/' so that composing new SmbResources will maintain the trailing slash requirement.- Returns:
- The last component of the URL associated with this SMB
resource or
smb://
if the resource issmb://
itself.
-
getType
int getType() throws CIFSException
Returns type of of object this SmbResource represents.- Returns:
- TYPE_FILESYSTEM, TYPE_WORKGROUP, TYPE_SERVER, TYPE_SHARE, TYPE_PRINTER, TYPE_NAMED_PIPE, or TYPE_COMM.
- Throws:
CIFSException
-
exists
boolean exists() throws CIFSException
Tests to see if the SMB resource exists. If the resource refers only to a server, this method determines if the server exists on the network and is advertising SMB services. If this resource refers to a workgroup, this method determines if the workgroup name is valid on the local SMB network. If thisSmbResource
refers to the rootsmb://
resourcetrue
is always returned. If thisSmbResource
is a traditional file or directory, it will be queried for on the specified server as expected.- Returns:
true
if the resource exists or is alive orfalse
otherwise- Throws:
CIFSException
-
resolve
SmbResource resolve(String name) throws CIFSException
Fetch a child resource- Parameters:
name
-- Returns:
- the child resource
- Throws:
CIFSException
-
fileIndex
long fileIndex() throws CIFSException
Get the file index- Returns:
- server side file index, 0 if unavailable
- Throws:
CIFSException
-
getAttributes
int getAttributes() throws CIFSException
Return the attributes of this file. Attributes are represented as a bitset that must be masked with ATTR_* constants to determine if they are set or unset. The value returned is suitable for use with the setAttributes() method.- Returns:
- the ATTR_* attributes associated with this file
- Throws:
CIFSException
-
isHidden
boolean isHidden() throws CIFSException
Tests to see if the file this SmbResource represents is marked as hidden. This method will also return true for shares with names that end with '$' such asIPC$
orC$
.- Returns:
true
if theSmbResource
is marked as being hidden- Throws:
CIFSException
-
isFile
boolean isFile() throws CIFSException
Tests to see if the file thisSmbResource
represents is not a directory.- Returns:
true
if thisSmbResource
is not a directory- Throws:
CIFSException
-
isDirectory
boolean isDirectory() throws CIFSException
Tests to see if the file thisSmbResource
represents is a directory.- Returns:
true
if thisSmbResource
is a directory- Throws:
CIFSException
-
canWrite
boolean canWrite() throws CIFSException
Tests to see if the file thisSmbResource
represents exists and is not marked read-only. By default, resources are considered to be read-only and therefore forsmb://
,smb://workgroup/
, andsmb://server/
resources will be read-only.- Returns:
true
if the resource exists is not marked read-only- Throws:
CIFSException
-
canRead
boolean canRead() throws CIFSException
Tests to see if the file thisSmbResource
represents can be read. Because any file, directory, or other resource can be read if it exists, this method simply calls theexists
method.- Returns:
true
if the file is read-only- Throws:
CIFSException
-
setReadWrite
void setReadWrite() throws CIFSException
Turn off the read-only attribute of this file. This is shorthand for setAttributes( getAttributes() & ~ATTR_READONLY ).- Throws:
CIFSException
-
setReadOnly
void setReadOnly() throws CIFSException
Make this file read-only. This is shorthand for setAttributes( getAttributes() | ATTR_READ_ONLY ).- Throws:
CIFSException
-
setAttributes
void setAttributes(int attrs) throws CIFSException
Set the attributes of this file. Attributes are composed into a bitset by bitwise ORing the ATTR_* constants. Setting the value returned by getAttributes will result in both files having the same attributes.- Parameters:
attrs
- attribute flags- Throws:
CIFSException
-
setFileTimes
void setFileTimes(long createTime, long lastModified, long lastAccess) throws CIFSException
Set the create, last modified and last access time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the createTime(), lastModified(), lastAccess() methods.
This method does not apply to workgroups, servers, or shares.- Parameters:
createTime
- the create time as milliseconds since Jan 1, 1970lastModified
- the last modified time as milliseconds since Jan 1, 1970lastAccess
- the last access time as milliseconds since Jan 1, 1970- Throws:
CIFSException
SmbUnsupportedOperationException
- if CAP_NT_SMBS is unavailable- See Also:
setCreateTime(long)
,setLastAccess(long)
,setLastModified(long)
-
setLastAccess
void setLastAccess(long time) throws CIFSException
Set the last access time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the lastAccess() method.
This method does not apply to workgroups, servers, or shares.- Parameters:
time
- the last access time as milliseconds since Jan 1, 1970- Throws:
CIFSException
SmbUnsupportedOperationException
- if CAP_NT_SMBS is unavailable
-
setLastModified
void setLastModified(long time) throws CIFSException
Set the last modified time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the lastModified() method.
This method does not apply to workgroups, servers, or shares.- Parameters:
time
- the last modified time as milliseconds since Jan 1, 1970- Throws:
CIFSException
-
setCreateTime
void setCreateTime(long time) throws CIFSException
Set the create time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the createTime() method.
This method does not apply to workgroups, servers, or shares.- Parameters:
time
- the create time as milliseconds since Jan 1, 1970- Throws:
CIFSException
SmbUnsupportedOperationException
- if CAP_NT_SMBS is unavailable
-
lastAccess
long lastAccess() throws CIFSException
Retrieve the last acces time of the file represented by thisSmbResource
- Returns:
- The number of milliseconds since the 00:00:00 GMT, January 1,
1970 as a
long
value - Throws:
CIFSException
-
lastModified
long lastModified() throws CIFSException
Retrieve the last time the file represented by thisSmbResource
was modified. The value returned is suitable for constructing aDate
object (i.e. seconds since Epoch 1970). Times should be the same as those reported using the properties dialog of the Windows Explorer program.- Returns:
- The number of milliseconds since the 00:00:00 GMT, January 1,
1970 as a
long
value - Throws:
CIFSException
-
createTime
long createTime() throws CIFSException
Retrieve the time thisSmbResource
was created. The value returned is suitable for constructing aDate
object (i.e. seconds since Epoch 1970). Times should be the same as those reported using the properties dialog of the Windows Explorer program. For Win95/98/Me this is actually the last write time. It is currently not possible to retrieve the create time from files on these systems.- Returns:
- The number of milliseconds since the 00:00:00 GMT, January 1,
1970 as a
long
value - Throws:
CIFSException
-
createNewFile
void createNewFile() throws CIFSException
Create a new file but fail if it already exists. The check for existence of the file and it's creation are an atomic operation with respect to other filesystem activities.- Throws:
CIFSException
-
mkdirs
void mkdirs() throws CIFSException
Creates a directory with the path specified by this SmbResource and any parent directories that do not exist. This method will fail when used withsmb://
,smb://workgroup/
,smb://server/
, orsmb://server/share/
URLs because workgroups, servers, and shares cannot be dynamically created (although in the future it may be possible to create shares).- Throws:
CIFSException
-
mkdir
void mkdir() throws CIFSException
Creates a directory with the path specified by thisSmbResource
. For this method to be successful, the target must not already exist. This method will fail when used withsmb://
,smb://workgroup/
,smb://server/
, orsmb://server/share/
URLs because workgroups, servers, and shares cannot be dynamically created (although in the future it may be possible to create shares).- Throws:
CIFSException
-
getDiskFreeSpace
long getDiskFreeSpace() throws CIFSException
This method returns the free disk space in bytes of the drive this share represents or the drive on which the directory or file resides. Objects other than TYPE_SHARE or TYPE_FILESYSTEM will result in 0L being returned.- Returns:
- the free disk space in bytes of the drive on which this file or directory resides
- Throws:
CIFSException
-
length
long length() throws CIFSException
Returns the length of this SmbResource in bytes. If this object is a TYPE_SHARE the total capacity of the disk shared in bytes is returned. If this object is a directory or a type other than TYPE_SHARE, 0L is returned.- Returns:
- The length of the file in bytes or 0 if this
SmbResource
is not a file. - Throws:
CIFSException
-
delete
void delete() throws CIFSException
This method will delete the file or directory specified by thisSmbResource
. If the target is a directory, the contents of the directory will be deleted as well. If a file within the directory or it's sub-directories is marked read-only, the read-only status will be removed and the file will be deleted. If the file has been opened before, it will be closed.- Throws:
CIFSException
-
copyTo
void copyTo(SmbResource dest) throws CIFSException
This method will copy the file or directory represented by this SmbResource and it's sub-contents to the location specified by the dest parameter. This file and the destination file do not need to be on the same host. This operation does not copy extended file attributes such as ACLs but it does copy regular attributes as well as create and last write times. This method is almost twice as efficient as manually copying as it employs an additional write thread to read and write data concurrently.
It is not possible (nor meaningful) to copy entire workgroups or servers.- Parameters:
dest
- the destination file or directory- Throws:
CIFSException
-
renameTo
void renameTo(SmbResource dest) throws CIFSException
Changes the name of the file thisSmbResource
represents to the name designated by theSmbResource
argument.
Remember:SmbResource
s are immutable and therefore the path associated with thisSmbResource
object will not change). To access the renamed file it is necessary to construct a new SmbResource.- Parameters:
dest
- AnSmbResource
that represents the new pathname- Throws:
CIFSException
NullPointerException
- If thedest
argument isnull
-
renameTo
void renameTo(SmbResource dest, boolean replace) throws CIFSException
Changes the name of the file thisSmbResource
represents to the name designated by theSmbResource
argument.
Remember:SmbResource
s are immutable and therefore the path associated with thisSmbResource
object will not change). To access the renamed file it is necessary to construct a new SmbResource.- Parameters:
dest
- AnSmbResource
that represents the new pathnamereplace
- Whether an existing destination file should be replaced (only supported with SMB2)- Throws:
CIFSException
NullPointerException
- If thedest
argument isnull
-
watch
SmbWatchHandle watch(int filter, boolean recursive) throws CIFSException
Creates a directory watch The server will notify the client when there are changes to the directories contents- Parameters:
filter
- see constants inFileNotifyInformation
recursive
- whether to also watch subdirectories- Returns:
- watch context, needs to be closed when finished
- Throws:
CIFSException
-
getOwnerGroup
SID getOwnerGroup() throws IOException
Return the resolved owner group SID for this file or directory- Returns:
- the owner group SID,
null
if not present - Throws:
IOException
-
getOwnerGroup
SID getOwnerGroup(boolean resolve) throws IOException
Return the owner group SID for this file or directory- Parameters:
resolve
- whether to resolve the group name- Returns:
- the owner group SID,
null
if not present - Throws:
IOException
-
getOwnerUser
SID getOwnerUser() throws IOException
Return the resolved owner user SID for this file or directory- Returns:
- the owner user SID,
null
if not present - Throws:
IOException
-
getOwnerUser
SID getOwnerUser(boolean resolve) throws IOException
Return the owner user SID for this file or directory- Parameters:
resolve
- whether to resolve the user name- Returns:
- the owner user SID,
null
if not present - Throws:
IOException
-
getSecurity
ACE[] getSecurity() throws IOException
Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory.Initially, the SIDs within each ACE will not be resolved however when getType(), getDomainName(), getAccountName(), or toString() is called, the names will attempt to be resolved. If the names cannot be resolved (e.g. due to temporary network failure), the said methods will return default values (usually S-X-Y-Z strings of fragments of).
Alternatively getSecurity(true) may be used to resolve all SIDs together and detect network failures.
- Returns:
- array of ACEs
- Throws:
IOException
-
getSecurity
ACE[] getSecurity(boolean resolveSids) throws IOException
Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory. If no DACL is present, null is returned. If the DACL is empty, an array with 0 elements is returned.- Parameters:
resolveSids
- Attempt to resolve the SIDs within each ACE form their numeric representation to their corresponding account names.- Returns:
- array of ACEs
- Throws:
IOException
-
getShareSecurity
ACE[] getShareSecurity(boolean resolveSids) throws IOException
Return an array of Access Control Entry (ACE) objects representing the share permissions on the share exporting this file or directory. If no DACL is present, null is returned. If the DACL is empty, an array with 0 elements is returned.Note that this is different from calling getSecurity on a share. There are actually two different ACLs for shares - the ACL on the share and the ACL on the folder being shared. Go to Computer Management > System Tools > Shared Folders > Shares and look at the Properties for a share. You will see two tabs - one for "Share Permissions" and another for "Security". These correspond to the ACLs returned by getShareSecurity and getSecurity respectively.
- Parameters:
resolveSids
- Attempt to resolve the SIDs within each ACE form their numeric representation to their corresponding account names.- Returns:
- array of ACEs
- Throws:
IOException
-
openRandomAccess
SmbRandomAccess openRandomAccess(String mode, int sharing) throws CIFSException
Opens the file for random access- Parameters:
mode
- access mode (r|rw)sharing
- flags indicating for which operations others may concurrently open the file- Returns:
- random access file, needs to be closed when finished
- Throws:
CIFSException
-
openRandomAccess
SmbRandomAccess openRandomAccess(String mode) throws CIFSException
Opens the file for random access- Parameters:
mode
- access mode (r|rw)- Returns:
- random access file, needs to be closed when finished
- Throws:
CIFSException
-
openOutputStream
OutputStream openOutputStream(boolean append, int openFlags, int access, int sharing) throws CIFSException
Opens an output stream writing to the file (write only, exclusive write access)- Parameters:
append
- whether to append to or truncate the inputopenFlags
- flags for open operationaccess
- desired file access flagssharing
- flags indicating for which operations others may open the file- Returns:
- output stream, needs to be closed when finished
- Throws:
CIFSException
-
openOutputStream
OutputStream openOutputStream(boolean append, int sharing) throws CIFSException
Opens an output stream writing to the file (write only, exclusive write access)- Parameters:
append
- whether to append to or truncate the inputsharing
- flags indicating for which operations others may open the file (FILE_SHARING_*)- Returns:
- output stream, needs to be closed when finished
- Throws:
CIFSException
-
openOutputStream
OutputStream openOutputStream(boolean append) throws CIFSException
Opens an output stream writing to the file (write only, read sharable)- Parameters:
append
- whether to append to or truncate the input- Returns:
- output stream, needs to be closed when finished
- Throws:
CIFSException
-
openOutputStream
OutputStream openOutputStream() throws CIFSException
Opens an output stream writing to the file (truncating, write only, sharable)- Returns:
- output stream, needs to be closed when finished
- Throws:
CIFSException
-
openInputStream
InputStream openInputStream(int flags, int access, int sharing) throws CIFSException
Opens an input stream reading the file (read only)- Parameters:
flags
- open flagsaccess
- desired access flagssharing
- flags indicating for which operations others may open the file (FILE_SHARING_*)- Returns:
- input stream, needs to be closed when finished
- Throws:
CIFSException
-
openInputStream
InputStream openInputStream(int sharing) throws CIFSException
Opens an input stream reading the file (read only)- Parameters:
sharing
- flags indicating for which operations others may open the file (FILE_SHARING_*)- Returns:
- input stream, needs to be closed when finished
- Throws:
CIFSException
-
openInputStream
InputStream openInputStream() throws CIFSException
Opens an input stream reading the file (read only, sharable)- Returns:
- input stream, needs to be closed when finished
- Throws:
CIFSException
-
close
void close()
Close/release the file This releases all resources that this file holds. If not using strict mode this is currently a no-op.- Specified by:
close
in interfaceAutoCloseable
- See Also:
AutoCloseable.close()
-
children
CloseableIterator<SmbResource> children() throws CIFSException
Fetch all children- Returns:
- an iterator over the child resources
- Throws:
CIFSException
-
children
CloseableIterator<SmbResource> children(String wildcard) throws CIFSException
Fetch children matching pattern, server-side filteringThe wildcard expression may consist of two special meta characters in addition to the normal filename characters. The '*' character matches any number of characters in part of a name. If the expression begins with one or more '?'s then exactly that many characters will be matched whereas if it ends with '?'s it will match that many characters or less.
Wildcard expressions will not filter workgroup names or server names.
- Parameters:
wildcard
-- Returns:
- an iterator over the child resources
- Throws:
CIFSException
-
children
CloseableIterator<SmbResource> children(ResourceNameFilter filter) throws CIFSException
- Parameters:
filter
- filter acting on file names- Returns:
- an iterator over the child resources
- Throws:
CIFSException
- See Also:
for a more efficient way to do this when a pattern on the filename is sufficient for filtering
-
children
CloseableIterator<SmbResource> children(ResourceFilter filter) throws CIFSException
- Parameters:
filter
- filter acting on SmbResource instances- Returns:
- an iterator over the child resources
- Throws:
CIFSException
- See Also:
for a more efficient way to do this when a pattern on the filename is sufficient for filtering
-
-