All Downloads are FREE. Search and download functionalities are using the official Maven repository.

jcifs.SmbResource Maven / Gradle / Ivy

There is a newer version: 2.1.10
Show newest version
/*
 * © 2017 AgNO3 Gmbh & Co. KG
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
package jcifs;


import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;


/**
 * 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.
 * 
 * @see jcifs.smb.SmbFile for the main implementation of this interface
 * @author mbechler
 */
public interface SmbResource extends AutoCloseable {

    /**
     * Gets the file locator for this file
     * 
     * The file locator provides details about
     * 
     * @return the fileLocator
     */
    SmbResourceLocator getLocator ();


    /**
     * The context this file was opened with
     * 
     * @return the context associated with this file
     */
    CIFSContext getContext ();


    /**
     * Returns the last component of the target URL. This will
     * effectively be the name of the file or directory represented by this
     * SmbResource 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 URL smb:// is also smb://. 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.
     *
     * @return The last component of the URL associated with this SMB
     *         resource or smb:// if the resource is smb://
     *         itself.
     */
    String getName ();


    /**
     * Returns type of of object this SmbResource represents.
     * 
     * @return TYPE_FILESYSTEM, TYPE_WORKGROUP, TYPE_SERVER, TYPE_SHARE,
     * TYPE_PRINTER, TYPE_NAMED_PIPE, or TYPE_COMM.
     * @throws CIFSException
     */
    int getType () 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 this SmbResource refers to the root
     * smb:// resource true is always returned. If
     * this SmbResource is a traditional file or directory, it will
     * be queried for on the specified server as expected.
     *
     * @return true if the resource exists or is alive or
     *         false otherwise
     * @throws CIFSException
     */
    boolean exists () throws CIFSException;


    /**
     * Fetch a child resource
     * 
     * @param name
     * @return the child resource
     * @throws CIFSException
     */
    SmbResource resolve ( String name ) throws CIFSException;


    /**
     * Get the file index
     * 
     * @return server side file index, 0 if unavailable
     * @throws CIFSException
     */
    long fileIndex () 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.
     *
     * @return the ATTR_* attributes associated with this file
     * @throws CIFSException
     */
    int getAttributes () 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 as IPC$ or C$.
     *
     * @return true if the SmbResource is marked as being hidden
     * @throws CIFSException
     */
    boolean isHidden () throws CIFSException;


    /**
     * Tests to see if the file this SmbResource represents is not a directory.
     *
     * @return true if this SmbResource is not a directory
     * @throws CIFSException
     */
    boolean isFile () throws CIFSException;


    /**
     * Tests to see if the file this SmbResource represents is a directory.
     *
     * @return true if this SmbResource is a directory
     * @throws CIFSException
     */
    boolean isDirectory () throws CIFSException;


    /**
     * Tests to see if the file this SmbResource represents
     * exists and is not marked read-only. By default, resources are
     * considered to be read-only and therefore for smb://,
     * smb://workgroup/, and smb://server/ resources
     * will be read-only.
     *
     * @return true if the resource exists is not marked
     *         read-only
     * @throws CIFSException
     */
    boolean canWrite () throws CIFSException;


    /**
     * Tests to see if the file this SmbResource represents can be
     * read. Because any file, directory, or other resource can be read if it
     * exists, this method simply calls the exists method.
     *
     * @return true if the file is read-only
     * @throws CIFSException
     */
    boolean canRead () throws CIFSException;


    /**
     * Turn off the read-only attribute of this file. This is shorthand for
     * setAttributes( getAttributes() & ~ATTR_READONLY ).
     *
     * @throws CIFSException
     */
    void setReadWrite () throws CIFSException;


    /**
     * Make this file read-only. This is shorthand for setAttributes(
     * getAttributes() | ATTR_READ_ONLY ).
     *
     * @throws CIFSException
     */
    void setReadOnly () 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.
     * 
     * @param attrs
     *            attribute flags
     * 
     * @throws CIFSException
     */
    void setAttributes ( int attrs ) 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
     * lastModified(), getLastModified(), and getDate() methods.
     * 
* This method does not apply to workgroups, servers, or shares. * * @param time * the last access time as milliseconds since Jan 1, 1970 * @throws CIFSException * @throws jcifs.smb.SmbUnsupportedOperationException * if CAP_NT_SMBS is unavailable */ void setLastAccess ( 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(), getLastModified(), and getDate() methods. *
* This method does not apply to workgroups, servers, or shares. * * @param time * the last modified time as milliseconds since Jan 1, 1970 * @throws CIFSException */ void setLastModified ( 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. * * @param time * the create time as milliseconds since Jan 1, 1970 * @throws CIFSException * @throws jcifs.smb.SmbUnsupportedOperationException * if CAP_NT_SMBS is unavailable */ void setCreateTime ( long time ) throws CIFSException; /** * Retrieve the last acces time of the file represented by this SmbResource * * @return The number of milliseconds since the 00:00:00 GMT, January 1, * 1970 as a long value * @throws CIFSException */ long lastAccess () throws CIFSException; /** * Retrieve the last time the file represented by this * SmbResource was modified. The value returned is suitable for * constructing a {@link java.util.Date} object (i.e. seconds since Epoch * 1970). Times should be the same as those reported using the properties * dialog of the Windows Explorer program. * * @return The number of milliseconds since the 00:00:00 GMT, January 1, * 1970 as a long value * @throws CIFSException */ long lastModified () throws CIFSException; /** * Retrieve the time this SmbResource was created. The value * returned is suitable for constructing a {@link java.util.Date} 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. * * @return The number of milliseconds since the 00:00:00 GMT, January 1, * 1970 as a long value * @throws CIFSException */ long createTime () 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 */ void createNewFile () 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 with smb://, smb://workgroup/, * smb://server/, or smb://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 */ void mkdirs () throws CIFSException; /** * Creates a directory with the path specified by this * SmbResource. For this method to be successful, the target * must not already exist. This method will fail when * used with smb://, smb://workgroup/, * smb://server/, or smb://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 */ void mkdir () 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. * * @return the free disk space in bytes of the drive on which this file or * directory resides * @throws CIFSException */ long getDiskFreeSpace () 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. * * @return The length of the file in bytes or 0 if this * SmbResource is not a file. * @throws CIFSException */ long length () throws CIFSException; /** * This method will delete the file or directory specified by this * SmbResource. 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 */ void delete () 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. * * @param dest * the destination file or directory * @throws CIFSException */ void copyTo ( SmbResource dest ) throws CIFSException; /** * Changes the name of the file this SmbResource represents to the name * designated by the SmbResource argument. *
* Remember: SmbResources are immutable and therefore * the path associated with this SmbResource object will not * change). To access the renamed file it is necessary to construct a * new SmbResource. * * @param dest * An SmbResource that represents the new pathname * @throws CIFSException * @throws NullPointerException * If the dest argument is null */ void renameTo ( SmbResource dest ) throws CIFSException; /** * Changes the name of the file this SmbResource represents to the name * designated by the SmbResource argument. *
* Remember: SmbResources are immutable and therefore * the path associated with this SmbResource object will not * change). To access the renamed file it is necessary to construct a * new SmbResource. * * @param dest * An SmbResource that represents the new pathname * @param replace * Whether an existing destination file should be replaced (only supported with SMB2) * @throws CIFSException * @throws NullPointerException * If the dest argument is null */ void renameTo ( SmbResource dest, boolean replace ) throws CIFSException; /** * Creates a directory watch * * The server will notify the client when there are changes to the directories contents * * @param filter * see constants in {@link FileNotifyInformation} * @param recursive * whether to also watch subdirectories * @return watch context, needs to be closed when finished * @throws CIFSException */ SmbWatchHandle watch ( int filter, boolean recursive ) throws CIFSException; /** * Return the resolved owner group SID for this file or directory * * @return the owner group SID, null if not present * @throws IOException */ SID getOwnerGroup () throws IOException; /** * Return the owner group SID for this file or directory * * @param resolve * whether to resolve the group name * @return the owner group SID, null if not present * @throws IOException */ SID getOwnerGroup ( boolean resolve ) throws IOException; /** * Return the resolved owner user SID for this file or directory * * @return the owner user SID, null if not present * @throws IOException */ SID getOwnerUser () throws IOException; /** * Return the owner user SID for this file or directory * * @param resolve * whether to resolve the user name * @return the owner user SID, null if not present * @throws IOException */ SID getOwnerUser ( boolean resolve ) 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. * * @return array of ACEs * @throws IOException */ ACE[] getSecurity () 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. * * @param resolveSids * Attempt to resolve the SIDs within each ACE form * their numeric representation to their corresponding account names. * @return array of ACEs * @throws IOException */ ACE[] getSecurity ( 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. * * @param resolveSids * Attempt to resolve the SIDs within each ACE form * their numeric representation to their corresponding account names. * @return array of ACEs * @throws IOException */ ACE[] getShareSecurity ( boolean resolveSids ) throws IOException; /** * Opens the file for random access * * @param mode * access mode (r|rw) * @param sharing * flags indicating for which operations others may concurrently open the file * @return random access file, needs to be closed when finished * @throws CIFSException * */ SmbRandomAccess openRandomAccess ( String mode, int sharing ) throws CIFSException; /** * Opens the file for random access * * @param mode * access mode (r|rw) * @return random access file, needs to be closed when finished * @throws CIFSException */ SmbRandomAccess openRandomAccess ( String mode ) throws CIFSException; /** * Opens an output stream writing to the file (write only, exclusive write access) * * @param append * whether to append to or truncate the input * @param openFlags * flags for open operation * @param access * desired file access flags * @param sharing * flags indicating for which operations others may open the file * @return output stream, needs to be closed when finished * @throws CIFSException */ 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) * * @param append * whether to append to or truncate the input * @param sharing * flags indicating for which operations others may open the file (FILE_SHARING_*) * @return output stream, needs to be closed when finished * @throws CIFSException */ OutputStream openOutputStream ( boolean append, int sharing ) throws CIFSException; /** * Opens an output stream writing to the file (write only, read sharable) * * @param append * whether to append to or truncate the input * @return output stream, needs to be closed when finished * @throws CIFSException */ OutputStream openOutputStream ( boolean append ) throws CIFSException; /** * Opens an output stream writing to the file (truncating, write only, sharable) * * @return output stream, needs to be closed when finished * @throws CIFSException */ OutputStream openOutputStream () throws CIFSException; /** * Opens an input stream reading the file (read only) * * @param flags * open flags * @param access * desired access flags * @param sharing * flags indicating for which operations others may open the file (FILE_SHARING_*) * @return input stream, needs to be closed when finished * @throws CIFSException */ InputStream openInputStream ( int flags, int access, int sharing ) throws CIFSException; /** * Opens an input stream reading the file (read only) * * @param sharing * flags indicating for which operations others may open the file (FILE_SHARING_*) * * @return input stream, needs to be closed when finished * @throws CIFSException */ InputStream openInputStream ( int sharing ) throws CIFSException; /** * Opens an input stream reading the file (read only, sharable) * * @return input stream, needs to be closed when finished * @throws CIFSException */ InputStream openInputStream () throws CIFSException; /** * Close/release the file * * This releases all resources that this file holds. If not using strict mode this is currently a no-op. * * @see java.lang.AutoCloseable#close() */ @Override void close (); /** * Fetch all children * * @return an iterator over the child resources * @throws CIFSException */ CloseableIterator children () throws CIFSException; /** * Fetch children matching pattern, server-side filtering * *

* The 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. * * @param wildcard * @return an iterator over the child resources * @throws CIFSException */ CloseableIterator children ( String wildcard ) throws CIFSException; /** * @param filter * filter acting on file names * @return an iterator over the child resources * @see SmbResource#children(String) for a more efficient way to do this when a pattern on the filename is * sufficient for filtering * @throws CIFSException */ CloseableIterator children ( ResourceNameFilter filter ) throws CIFSException; /** * @param filter * filter acting on SmbResource instances * @return an iterator over the child resources * @see SmbResource#children(String) for a more efficient way to do this when a pattern on the filename is * sufficient for filtering * @throws CIFSException */ CloseableIterator children ( ResourceFilter filter ) throws CIFSException; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy