Accessing Files Using Java With Samba JCIFS

1. Introduction

Cross-platform file exchange capabilities are crucial for the operation of computer networks. We can provide them with the Server Message Block (SMB) protocol and its widespread open-source implementation, Samba.

In this tutorial, we’ll learned how to access Samba resources from Java, without the need to mount or map a network drive.

2. The JCIFS library

Common Internet File System (CIFS) is a dialect of SMB. We’ll use the codelibs JCIFS implementation, which supports the newest SMB3 protocol.

Let’s add it with the Maven dependency:

<dependency>
    <groupId>org.codelibs</groupId>
    <artifactId>jcifs</artifactId>
    <version>3.0.1</version>
</dependency>

3. Setting up a Samba Server

Throughout this tutorial, we’ll use the Samba server set up in a VirtualBox guest machine. As a guest, we chose the Ubuntu server.

Next, let’s configure the VirtualBox host-only network adapter. Then, we narrow the DHCP address range to a single IP address: 192.168.56.101. This trick spares us a more sophisticated static IP setting.

During installation of the guest system, let’s add user jane. Afterward, we need to install Samba and add jane to the Samba users:

$ sudo smbpasswd -a jane

We need two folders for the shares:

$ mkdir /srv/samba/public /srv/samba/sambashare

To expose the folders, we set the 777 permission on them:

$ sudo chmod 777 /srv/samba/public /srv/samba/sambashare

Now, let’s edit the /etc/samba/smb.conf file:

$ sudo nano /etc/samba/smb.conf

Then we add two sections for shares:

[publicshare]
   comment = Anonymous Samba share
   path = /srv/samba/public
   read only = no
   guest ok = yes
   guest only = yes

[sambashare]
   comment = Samba on Ubuntu
   path = /srv/samba/sambashare
   read only = no
   browsable = yes

This way we created two Samba shares: an anonymous publicshare and a password-protected sambashare.

4. Simple Example

Let’s run a simple code to see the basics of reaching a Samba share. We’ll check a file located on publicshare:

// Default context
CIFSContext context = SingletonContext.getInstance();

LOGGER.info("#  Checking if file exists");
try (SmbFile file = new SmbFile("smb://192.168.56.101/publicshare/test.txt", context)) {
    if (file.exists()) {
        LOGGER.info("File " + file.getName() + " found!");
    } else {
        LOGGER.info("File " + file.getName() + " not found!");
    }
}

We can note elements necessary to establish the communication:

• CIFSContext maintains client configuration, credentials, and other related information. Here, it’s an instance of SingletonContext, which provides credentials suitable for an anonymous account
• SmbFile, which represents any kind of Samba resource. In our case, this is a file. We can place it into a try-with-resource block

Finally, we used the exists() method on the file object.

5. Authentication

We can create the CIFSContext object with credentials. Let’s list elements in the password-protected share sambashare:

NtlmPasswordAuthenticator credentials = new NtlmPasswordAuthenticator(
    "WORKGROUP",    // Domain name
    "jane",         // Username
    "Test@Password" // Password
);

// Context with authentication
CIFSContext authContext = context.withCredentials(credentials);

LOGGER.info("# Logging in with user and password");
try (SmbFile res = new SmbFile("smb://192.168.56.101/sambashare/", authContext)) {
    for (String element : res.list()) {
        LOGGER.info("Found element " + element);
    }
}

First, we created the NtlmPasswordAuthenticator object to store credentials. Then, we called the method withCredentials() on the existing context object. As a result, we obtained a child authContext with our credentials. Finally, the list() function showed all components of the share.

6. Working With Files and Directories

JCIFS provides a comprehensive set of functions for operating on files and folders. Let’s take a look at some of them.

6.1. Listing and Checking Files

With listFiles(), we can list files and folders. It returns an SmbFile object, which allows the use of many verification functions:

LOGGER.info("# List files and folders in Samba share");
try (SmbFile res = new SmbFile("smb://192.168.56.101/publicshare/", context)) {
    for (SmbFile element : res.listFiles()) {
        LOGGER.info("Found Samba element of name: " + element.getName());
        LOGGER.info("    Element is file or folder: " + (element.isDirectory() ? "file" : "folder"));
        LOGGER.info("    Length: " + element.length());
        LOGGER.info("    Last modified: " + new Date(element.lastModified()));
    }
}

In this example, we iterated through all items in the public folder. We determined whether it’s a file or a directory using the isDirectory() method. Next, we retrieved its length and modification time with the length() and getLastModified() methods, respectively.

6.2. Creating and Deleting Files

The JCFIS library allows creation and deletion of both files and directories. First, let’s work with files. We’ll create and immediately delete the New_file.txt file:

LOGGER.info("# Creating and deleting a file");
String fileName = "New_file.txt";
try (SmbFile file = new SmbFile("smb://192.168.56.101/publicshare/" + fileName, context)) {
    LOGGER.info("About to create file " + file.getName() + "!");
    file.createNewFile();

    LOGGER.info("About to delete file " + file.getName() + "!");
    file.delete();
}

We created an SmbFile object for a yet non-existent file. Then, we called its createNewFile() method. Finally, we applied the delete() function to remove the file. Notably, createNewFile() skips existing files without notification.

6.3. Creating and Deleting Folders

We can deal with folders in a similar way:

LOGGER.info("# Creating and deleting a folder");
String newFolderName = "New_folder/";
try (SmbFile newFolder = new SmbFile("smb://192.168.56.101/publicshare/" + newFolderName, context)) {
    LOGGER.info("About to create folder " + newFolder.getName() + "!");
    newFolder.mkdir();

    LOGGER.info("About to delete folder " + newFolder.getName() + "!");
    newFolder.delete();
}

We use the mkdir() method to create the folder and the delete() method to remove it. In the folder case, we must ensure that the folder doesn’t exist; otherwise, mkdir() will fail.

Let’s note that we should take great care when removing a folder with delete(). This method traverses and deletes the entire folder tree, with all files. Moreover, it’s able to remove the read-only permission on files.

In addition, we can create a whole directory tree with the mkdirs() method:

LOGGER.info("# Creating and deleting a subfolder with parent");
newFolderName = "New_folder/";
String subFolderName = "New_subfolder/";
try (SmbFile newSubFolder = new SmbFile("smb://192.168.56.101/publicshare/" + newFolderName + subFolderName, context)) {
    LOGGER.info("About to create folder " + newSubFolder.getName() + "!");
    newSubFolder.mkdirs();
}

We created a new directory, New_subfolder, along with the previously non-existent parent folder, New_folder.

6.4. Copying Files

The copyTo() method facilitates copying files and directories. We can use it on a single file or a folder. Let’s copy the entire contents of sambashare to publicshare:

LOGGER.info("# Copying files with copyTo");
try (SmbFile source = new SmbFile("smb://192.168.56.101/sambashare/", authContext); //needs authentication
    SmbFile dest = new SmbFile("smb://192.168.56.101/publicshare/", context)) { //public share
    source.copyTo(dest);
}

We copy by calling copyTo() on the Samba resource source and passing the destination resource dest to this method. Notably, these resources are different Samba shares.

We can also copy files between different servers. However, we cannot copy from the local filesystem, only between resources managed by Samba.

7. Working With Streams

The library provides SmbFileInputStream and SmbFileOutputStream, which override the standard Java InputStream and OutputStream abstract classes, respectively. Let’s copy a local file to the Samba share:

LOGGER.info("# Copying files with streams");
try (InputStream is = new FileInputStream("/home/joe/test.txt"); //Local file
     SmbFile dest = new SmbFile("smb://192.168.56.101/publicshare/test_copy.txt", context); //Samba resource
     OutputStream os = dest.getOutputStream()) {

    byte[] buffer = new byte[65536]; // using 64KB buffer
    int bytesRead;
    while ((bytesRead = is.read(buffer)) != -1) {
        os.write(buffer, 0, bytesRead);
    }
}

We read the local file with FileInputStream. Then, we copy content using an internal buffer. This method complements the copyTo() method when local files are in play.

8. Conclusion

In this article, we learned how to access Samba resources with the JCIFS library. For tests, we set up a simple Samba server. Then, we examined a shared resource and briefly learned about Samba authentication.

Then we focused on the file operations. First, we listed files and folders and checked their properties. Next, we performed create, copy, and delete operations on both files and directories. Finally, we used the JCIFS implementation of Java I/O streams to read and write Samba files.

As always, the code for the examples is available over on GitHub.