. . .

NetworkDrive Module

Introduction

A Module capable of writing files to network locations using the samba protocol.

Key Capabilities

Capability

Description

Network file writing

Write a file to a network destination using the samba protocol.
Information like host, username, password and samba share file path are necessary.

Network file reading

Read a file from a network destination using the same information

Encryption

Passwords for network authentification are stored in encrypted form. Password for
encryption is to be provided via module configuration.

Module Setup & Configuration

In order to write files, you need to set up an instance of NetworkCredentials that e.g. stores the host password. As you propably do not want that
password to be stored in plain text, this module provides an encryption mechanism.

Use the module configuration in order to provide an encryption password. If set once, all passwords will be encrypted or decrypted using that password.

Config name

Config value

Server password encryption key

/?~Ls9PaAN9Q%]]6

Example

Follow the steps provided below in order to write the desired file.

Frontend Use

  1. Set your credential encryption password via module configuration

  2. Create an instance of NetworkCredentials and provide host (e.g. 192.168.1.46), username and password for server athentification. In order to
    provide a domain, use the format username@domain for the username attribute.
    Note that the password will be encrypted using the server password encryption key from module configuration. Also, the Dashboard will display "No data" for your
    password even though it has been successfully saved. This is due to the implementation of the afterGetAll-method for NetworkCredentials.

  3. Create a NetworkOutFile object and set the reference for credentials, load up a file for content

  4. Set the path attribute according to the samba share settings with desired file name (e.g. "sambashare/test.pdf")

The module will then invoke the write operation.

Backend Use

  1. Follow instruction steps 1. - 4. as shown above

  2. Set an encryption password in module config

  3. You need to manually encrypt your password. The public class EncryptionHelper in com.apiomat.nativemodule.networkdrive does that for you

    String password = networkCredentials.getPassword( );
     
    try
    {
    /* Helper automatically reads encryption pasword from module config */
    EncryptionHelper helper = new EncryptionHelper( password, request );
    String encryptedPassword = helper.encrypt( );
     
    networkCredentials.setPassword( encryptedPassword );
    networkCredentials.save( );
    }
    catch ( Exception e )
    {
    NetworkDrive.AOM.logError( request.getApplicationName( ), e, false );
     
    e.printStackTrace( );
    }

  4. Manually care for writing to the network destination. Use the class NetworkWriteHelper in com.apiomat.nativemodule.networkdrive and Stick to following example

    NetworkWriteHelper helper = new NetworkWriteHelper( networkFile, request );
    try
    {
    /* will internally use the encryption helper to decrypt server password for authentification */
    helper.commit( );
    }
    catch ( IOException e )
    {
    NetworkDrive.AOM.throwException( 400, e.getMessage( ) );
     
    e.printStackTrace( );
    }

Follow the steps provided below in order to read the desired file.

Frontend Use

  1. Follow steps 1 and to as for writing files.

  2. Create a NetworkInFile object and set the reference for credentials

  3. Set the path attribute according to the samba share settings with desired file name (e.g. "sambashare/test.pdf")

The module will then invoke the read operation. You will find the file in the content attribute.

Backend Use

  1. Follow steps 1. - 3. as shown above

  2. Set an encryption password in the module configuration

  3. Encrypt your credentials password as explained in Backend Use for writing files

  4. Now use the NetworkReadHelper class to achieve your goal

    NetworkReadHelper helper = new NetworkReadHelper( networkFile, request );
    try
    {
    helper.commit( );
    }
    catch ( IOException e )
    {
    NetworkDrive.AOM.throwException( 400, e.getMessage( ) );
     
    e.printStackTrace( );
    }

Limitations

If any information like path or credentials are missing, you will fail.

Other sources of error might be

  • failing authentication

  • server not found error

  • missing file read/write permissions

If you encounter some error, doublecheck your data provided. Invoke the write process again with renewing
the path or content attributes.


Detailled Module Workflow

Module Config

In order to read or write files, you need to set up an instance of NetworkCredentials that e.g. stores the host password. As you propably do not want that password to be stored in clear text, this module provides an encryption mechanism.

Use the module configuration in order to provide an encryption password. If set once, all passwords will be encrypted or decrypted using that encryption password.

Classes

Class name

Attributes

Description

NetworkCredentials

host: server host name like "192.168.1.46"
username: a registered user's login name on that server. If you
want to provide a domain, do it like username@domain
password: that user's password. Stored in encrypted form.
Dashboard shows no data.

Container for server access credentials for a user in reusable form.

NetworkFile

credentials: reference to a NetworkCredentials object for
server access
content: File object for the file you want to send or the file that
you receive
path: samba's shared folder's path with desired file name
e.g. "sambashare/test.pdf"

Class for all information as like file to write or read, authentification
credentials and samba share path

NetworkInFile

Subclass of NetworkFile for files being read from a samba share
location

NetworkOutFile

Subclass of NetworkFile for files being written to a samba share
location

Sequence

After setting a reference from NetworkFile to NetworkCredentials and providing a file as NetworkFile's content, the module invokes the afterPut-method writing to the destination after providing for the path attribute.
Note that the Module automatically prepends the host attribute with "smb://" internally.