Managed File Transfer and Security Solutions

Scripting SSH sessions using Java

Overview

This tutorial will demonstrate how to automate an SSH session using SSH Factory or Secure iNet Factory and issue commands in batch mode (non-interactive).

There are three ways to accomplish this. Write Java code that will make use of SshSession class, write Java code that will make use of SshScript class or write an SSCL command script.  Both SshSession and SshScript class are present in SSH Factory and Secure iNet Factory components. SSCL is included only in SSH Factory.

Prerequisites

• An account on a machine running SSH server.
• SSH Factory or Secure iNet Factory

SSH Scripting using SshSession

SshSession is a convenience class that presents a very simple, straightforward API for automating SSH sessions.

There are two ways to define a class that uses SshSession. If you want to listen to events fired by the underlying SSH instance  then you could have your class implement the SshListener interface or extend the SshAdapater class, which already implements SshListener and provide a default implementation.

//import the necessary classes
import com.jscape.inet.ssh.SshAdapter;

//extend SshAdapter and implement its interface.
//we could then add ourself to SshSession as an ssh event listener
public class SshSessionTutorial extends SshAdapter {
   …
}

Or if not interested on listening to SSH events then a plain Java class will do.

public class SshSessionTutorial {
   …
}

Below is a code snippet that uses SshSession class to connect to an SSH server and issue commands once a session is established.

//import the necessary classes
import com.jscape.inet.ssh.SshException;
import com.jscape.inet.ssh.SshSession;
import com.jscape.inet.ssh.util.SshParameters;
…
   public void executeSshScript(String hostname, String username, String password)
      throws SshException
   {
      //initialize and create an SshSession object
      SshParameters sshParams = new SshParameters(hostname, username, password);
      SshSession session = new SshSession(sshParams);
      session.setShellPrompt("$");

      //attempt to connect and set timeout to 1000ms to disconnect if unable to.
      session.connect(1000);

      //issue commands and print command output
      String dirListing = session.send("ls -al");
      System.out.println(dirListing);
      String pwd = session.send("pwd");
      System.out.println(pwd);

      //disconnect session
      session.disconnect();          
   }
…

Download the complete Java code here: SshSessionTutorial.java

SSH Scripting Using SshScript

SshScript class provides a simple way of running a set of commands against a SSH server. It’s a bit more involved than SssSession but offers more control like the ability to have an SshScriptListener to capture events relating to every command submitted.

When defining your Java class that makes use of the SshScript class you may have it implement SshListener or extend SshAdapter if you want to listen to events fired by the Ssh instance bound to it. You may also want to have your class implement SshScriptListener to capture events that occur during the execution of each command.

//import the necessary class/interface
import com.jscape.inet.ssh.SshAdapter;
import com.jscape.inet.ssh.SshScriptListener;

public class SshScriptTutorial extends SshAdapter implements SshScriptListener {
   …
}

If not interested in capturing any events a plain class definition will do.

public class SshScriptTutorial {
   …
}

Below is a code snippet that uses SshScript class to connect to an SSH server and issue commands once a session is established.

When instantiating an SshScript object, an Ssh object is passed to its constructor and it gets bound to that Ssh object. When that Ssh object is connected all the tasks added to the SshScript instance are executed. A command is added by instantiating an SshTask object and adding it to an SshScript instance.

//import the necessary classes
import com.jscape.inet.ssh.Ssh;
import com.jscape.inet.ssh.SshException;
import com.jscape.inet.ssh.SshScript;
import com.jscape.inet.ssh.SshTask;
import com.jscape.inet.ssh.util.SshParameters;
…
   public void executeSshScript(String hostname, String username, String password)
      throws SshException
   {
      // assumes that SSH shell prompt is "$" .. this MUST match exactly
      String shellPrompt = "$";     

      // initialize and create new Ssh instance
      SshParameters sshParams = new SshParameters(hostname,username,password);
      Ssh ssh = new Ssh(sshParams);

      // register this class (if applicable) to receive Ssh events
      ssh.addSshListener(this);

      // create new script object and bind to the given ssh object
      SshScript script = new SshScript(ssh);

         // register this class (if applicable) to receive task events
      script.addSshScriptListener(this);

      // add tasks to script object
      script.addTask(new SshTask(shellPrompt, "ls -al", shellPrompt));
      script.addTask(new SshTask(shellPrompt, "pwd", shellPrompt));

      // connect to SSH server and execute script
      ssh.connect();

      // wait until last task is complete
      while(!script.isComplete()) {
         try {
            Thread.sleep(100);
         } catch(Exception e) {}
      }

      // disconnect from server
      ssh.disconnect();
   } 
…   

Download the complete Java code here: SshScriptTutorial.java

SSH Scripting using SSCL

Above you have seen two ways to script an SSH session. It requires a bit of Java coding and while relatively easy is still a bit more involved.

Here we’ll show you how to do away with the Java programming altogether and use SSCL (Secure Shell Command Line) component to automate an SSH session. SSCL uses a simple scripting language. Below is a sequence of SSCL commands that accomplish the same task as the above Java codes.

prompt hostname "Enter SSH hostname: "
prompt username "Enter SSH username: "
prompt password "Enter SSH password: "
set secure true
connect
send "ls -al"
send "pwd"
sendnowait "exit"
wait 3
disconnect

The above commands can be written into a file and passed to SSCL component for direct execution like so:

java -jar /path/to/sshfactory.jar -f sscl_commands_file.txt

Please note that SSCL is only available with SSH Factory and is not present on Secure iNet Factory.

For SSCL command reference see link below.

Summary

The motivation for automating an SSH session are plentiful. Things like router configuration, user management and other administration tasks are good examples. Basically anything that you interactively do inside an SSH session that is repetitive. Scripting makes it easyly repeatable and less error prone.

References

SSH Factory for Java
http://www.jscape.com/sshfactory/index.html

Secure iNet Factory
http://www.jscape.com/secureinetfactory/index.html

SshSession
http://www.jscape.com/sshfactory/docs/html/overview21.html

SshScript
http://www.jscape.com/sshfactory/docs/html/overview20.html

SSCL
http://www.jscape.com/sshfactory/docs/html/overview.html

Sending Email Securely Using Gmail and SMTP SSL

Overview

Google allow Gmail account users to access their account using any capable email client such as Microsoft Outlook, Apple Mail.app and others. For this to work Gmail provides POP and IMAP access to these client applications so that they could access emails stored on Gmail servers. In addition to this, Gmail provides access to its SMTP server to allow these clients to send emails through it.

In order to prevent abuse such as spamming and to provide increased security the Gmail SMTP server requires that you connect using SMTP SSL and login using your account credentials prior to sending any mail.

The purpose of this article is to demonstrate how to securely connect to the Gmail SMTP server and send mail using a bit of Java code which make use of com.jscape.inet.smtpssl.SmtpSsl class found in Secure iNet Factory.

The procedures in this article may also apply to other SMTP servers that provide secure SSL/TLS access.

Prerequisites

• A Gmail account
• Secure iNet Factory
• Java 1.4 or greater

Using SmtpSsl to Send Email via Gmail SMTP Server

The SmtpSsl class implements basic functionality of a secure SMTP client using SSL/TLS. It supports both implicit SSL/TLS on port 465 (default) and explicit SSL/TLS using STARTTLS command on port 25.

Below is a Java code snippet that shows how to use SmtpSsl to connect to Gmail using implicit SSL, authenticate and then send an email.

//import necessary classes
import com.jscape.inet.smtpssl.SmtpSsl;
import com.jscape.inet.email.EmailMessage;
…
         // create a new SmtpSsl instance connecting securely via port 465 using implicit SSL
         smtp = new SmtpSsl("smtp.gmail.com", 465);

         // establish secure connection
         smtp.connect();

         // login using gmail account details
         smtp.login(username, password);

         // create new email message
         EmailMessage message = new EmailMessage();
         message.setTo(to);
         message.setFrom(username);
         message.setSubject("Sending email via Gmail SMTP");
         message.setBody("This is the body of the message");

         // send message
         smtp.send(message);

         // disconnect     
         smtp.disconnect();     
…

Download the complete Java code here: SmtpGmail.java

Summary

This article demonstrates how straightforward and easy it is to connect to a secure SMTP server, in this case Gmail, and then send an email.

References

Gmail - Configuring other mail clients
Class SmtpSsl

Retrieving Email Securely from Gmail using POP SSL

Overview

Google allow Gmail account users to access their account using any capable email client such as Microsoft Outlook, Apple Mail.app and others. For this to work Gmail provides POP and IMAP access to these client applications so that they could access emails stored on Gmail servers. To retrieve mails however Gmail require that SSL be used when accessing their POP server. This enables encryption to secure mail during transmission.

The purpose of this article is to demonstrate how to securely connect to the Gmail server and retrieve mails using a bit of Java code that make use of com.jscape.inet.smtpssl.PopSsl class found in Secure iNet Factory.

The procedures in this article may also apply to other POP servers that provide secure SSL/TLS access.

Prerequisites

• A Gmail account
• Secure iNet Factory
• Java 1.4 or greater

Using PopSsl to Retrieve Email Securely from Gmail

The PopSsl class provides an easy to use client interface for securely communicating with POP3 servers using SSL/TLS.  The PopSsl class provides both implicit and explicit SSL/TLS connections.  Implicit SSL/TLS connections are made by default using remote port 995. Explicit SSL/TLS connections are made using an unencrypted connection to port 110 of a POP3 server and then switching to an encrypted mode using the STLS command prior to sending any additional data.

An implicit SSL/TLS connection on port 995 is what’s required to connect to Gmail POP server. Below is a complete Java code that uses PopSsl class to retrieve mails from Gmail.

//import the necessary classes
import com.jscape.inet.email.EmailMessage;
import com.jscape.inet.popssl.PopSsl;


public class PopSslGmail {

   public static void main(String[] args) {
      String hostname = "pop.gmail.com";
      String username = "username@gmail.com"; //CHANGE THIS
      String password = "password"; //CHANGE THIS

      try {
         // create new PopSsl instance
         PopSsl ssl = new PopSsl(hostname, 995, username, password);
         ssl.setDebug(true);

         // establish SSL/TLS connection
         ssl.connect();

         // get message count
         int count = ssl.getMessageCount();

         // get each message and print subject
         for(int i = 1; i <= count; ++i) {
            EmailMessage msg = ssl.getMessage(i);
            System.out.println("Subject: " + msg.getSubject());       
         }

         // disconnect
         ssl.disconnect();     
      } catch(Exception e) {
         e.printStackTrace();
      }
   }

}

Download the source code file here: PopSslGmail.java

Summary

This article demonstrates how straightforward and easy it is to connect to a secure POP server, in this case Gmail, and then retrieve emails.

References

PopSsl Overview
PopSsl Javadoc
Gmail - Configuring other mail clients

Secure FTP using Java and FTPS (FTP over SSL)

Overview

This article will demonstrate how to securely transfer files using the FTPS (FTP over SSL) protocol and the components provided in Secure FTP Factory or Secure iNet Factory. To see what else these components has to offer please download a FREE 30 day evaluation here, Secure FTP Factory Evaluation and Secure iNet Factory Evaluation.

Note: This example demonstrates transferring files using FTPS (FTP over SSL). If you want to learn how to use SFTP (FTP over SSH) protocol to transfer files then please see the article Secure FTP using Java and SFTP (FTP over SSH).

Prerequisites

• An FTP server with SSL support such as JSCAPE MFT Server
• JDK 1.4 or above
• Secure FTP Factory or Secure iNet Factory

Downloading Files From an FTPS Server using Ftps Class

The Ftps class provides an easy to use programming interface for securely exchanging data with an FTP (File Transfer Protocol) server using SSL (Secure Sockets Layer)

There are two ways to define a class that use Ftps class. If you want to listen to events fired by the underlying FTP instance you could have your class implement the FtpListener interface or extend the FtpAdapater class, which already implements FtpListener and provide a default implementation.

//import the necessary class
import com.jscape.inet.ftp.FtpAdapter;

public class FtpsDownloadTutorial extends FtpAdapter {
   …
}

Or if not interested on listening to FTP events then a plain Java class will do.

public class FtpsDownloadTutorial {
   …
}

Below is a code snippet that uses Ftps class to connect an FTP server with SSL support and download files matching a given regex filter.

//import the necessary classes
import com.jscape.inet.ftp.FtpException;
import com.jscape.inet.ftps.Ftps;

…
   // perform multiple file download
   public void doDownload(String hostname, String username, String password, String filter)
      throws FtpException
   {
      Ftps ftp = new Ftps(hostname, username, password);
      ftp.setDebug(true);
      ftp.setTimeout(1000);

      //capture Ftp related events if applicable (if your class extends FtpAdapter)
      ftp.addFtpListener(this);

      //establish connection to the server
      ftp.connect();

      //set file transfer mode to BINARY. if transferring text it's best to use setAscii()
      ftp.setBinary();

      //download files that matched the given regex filter
      ftp.mdownload(filter);

      //disconnect from server
      ftp.disconnect();
   }
…

Download the complete Java code for this tutorial here: FtpsDownloadTutorial.java

Summary

Being able to transfer files securely is sometimes a critical requirement to some applications. Using Secure FTP Factory or Secure iNet Factory you can quickly and easily enable such functionality within your applications.

References

Ftps Class Overview
Ftps Class Javadoc
FTPS Wiki

SSH using Java

Overview

This article will demonstrate how using the SSH classes in SSH Factory or Secure iNet Factory components you can develop a console based interactive SSH shell.

To see what else these components have to offer please download a FREE 30 day evaluation here: SSH Factory Evaluation and Secure iNet Factory Evaluation.

Prerequisites

• An SSH server
• JDK 1.4 or above
• SSH Factory or Secure iNet Factory 

Using Ssh Class to Connect to an SSH Server

The Ssh class provides an easy to use programming interface for communicating with SSH (Secure SHell) servers. This tutorial focuses on using the class by itself to communicate with an SSH server like a regular interactive SSH client. To see it used as an underlying object for SSH scripting see Scripting SSH sessions using Java and JSCAPE Components

Please note that the Ssh Class is present in both SSH Factory and Secure iNet Factory.

There are two ways to define a class that make use of the Ssh class. If you want to listen to events fired by the SSH instance you could have your class implement the SshListener interface or extend the SshAdapater class, which already implements SshListener and provide a default implementation.

//import the necessary interface/class
import com.jscape.inet.ssh.SshListener;

public class SshTutorial implements SshListener {
   …
}

Or if not interested on listening to SSH events then a plain Java class will do.

public class SshTutorial {
   …
}

Below is a code snippet that uses Ssh class to connect an SSH server. Once a connection with an SSH server is established the user will then be able to issue interactive commands within the session.

//import the necessary classes
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;

import com.jscape.inet.ssh.Ssh;
import com.jscape.inet.ssh.util.SshParameters;

…

   // state of SSH connection
   private boolean connected = false;

   public void connectSsh(String hostname, String username, String password) {
      Ssh ssh = null;

      try {
         // create/initialize new Ssh instance
         SshParameters params = new SshParameters(hostname, username, password);
         ssh = new Ssh(params);

         // register to capture events if applicable (if your class extends
         // SshAdapter or implements SshListener)
         ssh.addSshListener(this);

         System.out.println("Connecting please wait...");

         // connect
         ssh.connect();

         // get output stream for writing data to SSH server
         OutputStream out = ssh.getOutputStream();

         // holds line entered at console
         String line = null;

         // read session commands from user via standard input
         BufferedReader bin =
            new BufferedReader(new InputStreamReader(System.in));

         // read data from console
         while (connected && (line = bin.readLine()) != null) {
            // send line with LF to SSH server
            line += "\n";
            try {
               out.write(line.getBytes());
               out.flush();
            } catch(Exception ioe) {
               // set this flag to false to exit this loop when exception occurs
               connected = false;
            }       
         }                    
      } catch (Exception e) {
         e.printStackTrace();                   
      } finally {
         try {
            if(connected) {
               ssh.disconnect();     
            }
         } catch(Exception e) {

         }                    
      }
   }
…

Download the complete Java code for this tutorial here: SshTutorial.java

Summary

There are maybe few rare cases that an application will require an interactive SSH client. The power of the Ssh class lies in its ability to be used in a non-interactive (batch mode) and automate commands issued on an SSH server.

References

Ssh Class Overview
Ssh Class Javadoc
Secure Shell

Retrieving Email from POP3 Server Using Java

Overview

This article will demonstrate how to retrieve email from a POP3 server using the components provided in Secure iNet Factory.

To see what else Secure iNet Factory has to offer Download a FREE 30 day Secure iNet Factory Evaluation

Prerequisites

• Account and POP server details
• JDK 1.4 or above
• Secure iNet Factory

Retrieving Email Using the Pop Class

The Pop class provides an easy to use programming interface for communicating with POP3 (Post Office Protocol version 3) servers.

Below is a sample code the illustrates how to use the Pop class to connect to a POP3 server then iterate and retrieve all available email messages. It demonstrate saving the messages as well as its attachments if available.

import java.io.BufferedReader;
import java.io.File;
import java.io.FileOutputStream;
import java.io.InputStreamReader;
import java.io.IOException;

import java.util.Enumeration;

import com.jscape.inet.email.EmailMessage;
import com.jscape.inet.mime.Attachment;
import com.jscape.inet.mime.MimeException;
import com.jscape.inet.pop.Pop;
import com.jscape.inet.pop.PopException;

public class PopAttachmentsTutorial {
    private static File messagesDir = new File("msg");
    private static File attachmentsDir = new File("attach");
    static BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));

    // get messages from Pop mailbox
    public void getMessages(String hostname, String username, String password)
    throws PopException, MimeException, IOException {
        // ensure that messages directory is valid
        if(!messagesDir.exists()) {
            messagesDir.mkdir();
        }

        // ensure that attachments directory is valid
        if(!attachmentsDir.exists()) {
            attachmentsDir.mkdir();
        }

        // connect and login
        Pop pop = new Pop(hostname,username,password);
        pop.connect();       

                  System.out.println("Retrieving messsages...");       

        // get message count
         int messageCount = pop.getMessageCount();
        if(messageCount < 1) {
            System.out.println("No messages found");
        }

        // get messages and write messages to disk
         for(int i = 1; i <= messageCount; ++i) {
            EmailMessage msg = (EmailMessage)pop.getMessage(i);
            File f = new File(messagesDir,"msg" + i + ".txt");
            FileOutputStream fout = new FileOutputStream(f);
            fout.write(msg.getMessage());
            fout.close();
            System.out.println("Retrieved message: " + f.getAbsoluteFile());

            // write attachments to disk
            int attachnum = 0;
            Enumeration attachments = msg.getAttachments();
            while(attachments.hasMoreElements()) {
                ++attachnum;
                Attachment attach = (Attachment)attachments.nextElement();
                String attachmentFileName = attach.getFilename();
                if(attachmentFileName == null) {
                    attachmentFileName = "attachment" + i + "-" + attachnum;
                }

                String fileName = attach.getFilename();
                if(fileName == null) {
                   fileName = System.currentTimeMillis() + ".txt";
                }
                File attFile = new File(attachmentsDir,fileName);
                FileOutputStream attOut = new FileOutputStream(attFile);
                try {
                    attOut.write(attach.getFileData());
                    attOut.close();
                    System.out.println("Retrieved attachment: " + attFile.getAbsoluteFile());
                }
                catch(Exception e) {
                    throw new PopException("unable to decode file attachment");
                }
            }
        }
        pop.disconnect();
    }

    public static void main(String[] args) {
        String hostname;
        String username;
        String password;

        try {
            System.out.print("Enter Pop3 hostname (e.g. mail.domain.com): ");
            hostname = reader.readLine();
            System.out.print("Enter Pop3 Username: ");
            username = reader.readLine();
            System.out.print("Enter Pop3 Password: ");
            password = reader.readLine();
            PopAttachmentsTutorial tutorial = new PopAttachmentsTutorial();
            tutorial.getMessages(hostname,username,password);
        }
        catch(Exception e) {
            e.printStackTrace();
        }
    }
}

Download the source code here: PopAttachmentsTutorial.java

Summary

Using the Secure iNet Factory components retrieving email from a POP3 or IMAP server is a very simple task.

This article focus on the POP3 protocol but using the IMAP protocol to retrieve email are very much the same, the main difference being that the com.jscape.inet.pop.Pop class is used instead of the com.jscape.inet.imap.Imap class.

References

Pop Class Overview
Pop Class Javadoc
POP3 Wiki

Secure FTP using Java and SFTP (FTP over SSH) protocol

Overview

This article will demonstrate how to securely transfer files using the SFTP (FTP over SSH) protocol and the components provided in Secure FTP Factory or Secure iNet Factor. To see what else these components have to offer please download a FREE 30 day evaluation here, Secure FTP Factory Evaluation and Secure iNet Factory Evaluation.

Note: This example demonstrates transferring files using SFTP (FTP over SSH). If you want to learn how to use FTPS (FTP over SSL) protocol to transfer files then please see the article Secure FTP using Java and FTPS (FTP over SSL)

Prerequisites

• An SSH server with SFTP subsystem enabled
• JDK 1.4 or above
• Secure FTP Factory or Secure iNet Factory

Downloading Files From an SFTP Server using the Sftp Class

The Sftp class provides an easy to use client application programming interface for transferring files between a client and an SFTP subsystem within an SSH (Secure SHell) server.

Please note that the Sftp class is included in both Secure FTP Factory and Secure iNet Factory. 

There are two ways to define a class that use Sftp class. If you want to listen to events fired by the Sftp instance you could have your class implement the SftpListener interface or extend the SftpAdapater class, which already implements SftpListener and provides a default implementation.

//import the necessary interface/class
import com.jscape.inet.sftp.events.SftpAdapter;

public class SFtpMdownloadTutorial extends SftpAdapter {
   …
}

Or if not interested on listening to SFTP events then a plain Java class will do.

public class SFtpMdownloadTutorial {
   …
}

The following code snippet uses the Sftp class to connect to an SFTP subsystem within an SSH server and download files matching a given regex filter.

//import the necessary classes
import com.jscape.inet.sftp.Sftp;
import com.jscape.inet.sftp.SftpException;
import com.jscape.inet.ssh.util.SshParameters;

…

   // perform multiple file download
   public void doDownload(String sftpHostname, String sftpUsername, String sftpPassword, String filter)
      throws SftpException
   {
      // create/initialize an Sftp instance
      SshParameters params = new SshParameters(sftpHostname, sftpUsername, sftpPassword);                 
      Sftp ftp = new Sftp(params);

      //capture FTP related events when applicable (if your class extends SftpAdapter or implements FtpListener)
      ftp.addSftpListener(this);

      // establish connection
      ftp.connect();       

      // download files matching regex filter
      ftp.mdownload(filter);

      // disconnect
      ftp.disconnect();
   }   
…

Download the complete Java code for this tutorial here: SFtpMdownloadTutorial.java

Summary

Being able to transfer files securely is sometimes a critical requirement to some applications. Using Secure FTP Factory or Secure iNet Factor you can quickly and easily enable such functionality within your applications.

References

Sftp Class Overview
Sftp Class Javadoc
SFTP Wiki

Sending Email with Attachments using Java

Overview

This article will demonstrate how to send an email message that includes a file attachment using the components provided in Secure iNet Factory.

To see what else Secure iNet Factory has to offer Download a FREE 30 day Secure iNet Factory Evaluation.

Prerequisites

• SMTP account and server details
• JDK 1.4 or above
• Secure iNet Factory

Sending Email with Attachments using the Smtp Class

The Smtp class provides an easy to use programming interface for communicating with SMTP (Simple Mail Transport Protocol) servers.

There are two ways to define a class that will use the Smtp class. If you want to listen to events fired by the Smtp instance you could have your class implement the SmtpListener interface or extend the SmtpAdapter class, which already implements SmtpListener and provide a default implementation.

//import the necessary interface/class
import com.jscape.inet.smtp.SmtpAdapter;

public class SmtpAttachmentTutorial extends SmtpAdapter {
   …
}

Or if not interested on listening to Smtp events then a plain Java class will do.

public class SmtpAttachmentTutorial {
   …
}

The following code snippet illustrates the steps needed to compose an email message including attaching a file then connecting to an SMTP server and sending the email.

import java.io.File;
import java.io.IOException;

import com.jscape.inet.smtp.Smtp;
import com.jscape.inet.smtp.SmtpException;
import com.jscape.inet.mime.Attachment;
import com.jscape.inet.mime.MimeException;
import com.jscape.inet.email.EmailMessage;

…

   public void sendMessage(String hostname, String to, String from, String subject, String body, String attachment)
      throws SmtpException,
             IOException,
             MimeException
   {

      // create new Smtp instance
      Smtp smtp = new Smtp(hostname);

      // enable debugging ... all output is sent to System.out
      smtp.setDebug(true);

      // capture SMTP related events
      smtp.addSmtpListener(this);

      // connect to mail server
      smtp.connect();

      // create new email message
      EmailMessage email = new EmailMessage();

      // set recipient address
      email.setTo(to);

      // set from address
      email.setFrom(from);

      // set subject
      email.setSubject(subject);

      // set body
      email.setBody(body);

      // add file attachment to message
      email.addAttachment(new Attachment(new File(attachment)));

      // send email message
      smtp.send(email);

      // disconnect from SMTP server
      smtp.disconnect();
   }
…

Download the complete source code here: SmtpAttachmentTutorial.java

Summary

The requirement for sending emails within an application is very common, from sending registration confirmation to periodic email notifications and some cases it is necessary to attach files on these emails. Using the Secure iNet Factory components adding file attachments to your outbound email messages is a very simple task.

References

Smtp Class Overview
Smtp Class Javadoc
SMTP Wiki

Telnet using Java

Overview

This article will demonstrate how using the Telnet component present in both SSH Factory and Secure iNet Factory you can establish an interactive Telnet session with a Telnet server.

To see what else these products have to offer please download a FREE 30 day evaluation here: SSH Factory Evaluation and Secure iNet Factory Evaluation.

The Telnet client component provides a method for communicating with a Telnet server. The process for establishing an interactive session with a Telnet server using the Telnet component is as follows:

1.  Creating a new Telnet instance
2.  Implementing a TelnetListener
3.  Registering a TelnetListener
4.  Establishing a connection
5.  Performing option negotiation
6.  Receiving data
7.  Sending data
8.  Releasing a connection

Each of these processes is described in the sections below.

Creating a new Telnet instance

To create a new Telnet instance ensure that the com.jscape.inet.telnet package is included in your import statements and create a new Telnet instance providing the Telnet server hostname as an argument.

Telnet telnet = new Telnet(hostname);

Implementing a TelnetListener

The Telnet component is one of the few components which MUST have a registered event listener. The reason for this will be clear later. The following is a sample implementation of the TelnetListener interface. A TelnetListener instance must be created and registered with the Telnet instance prior to invoking the Telnet#connect method to ensure that all data sent by the Telnet server is captured.

public class MyTelnetListener implements TelnetListener {
  public void connected(TelnetConnectedEvent event) {
  }

  public void disconnected(TelnetDisconnectedEvent event) {
  }

  public void doOption(DoOptionEvent event) {
  }

  public void dontOption(DontOptionEvent event) {
  }

  public void willOption(WillOptionEvent event) {
  }

  public void wontOption(WontOptionEvent event) {
  }

  public void doSubOption(DoSubOptionEvent event) {
  }

  public void dataReceived(TelnetDataReceivedEvent event) {
  }
}

Registering a TelnetListener

To register a listener invoke the Telnet#addTelnetListener method providing a TelnetListener instance as its argument.

Telnet telnet = new Telnet(hostname);
MyTelnetListener listener = new MyTelnetListener();
telnet.addTelnetListener(listener);

Establishing a connection

Once a Telnet instance has been created and a TelnetListener registered you may establish a connection to the Telnet server by invoking the Telnet#connect method.

telnet.connect();

Performing option negotiation

Upon establishing a connection the process of option negotiation will begin. Option negotiation is a communications process for the Telnet client and the Telnet server to come up with a set of agreed upon protocols. An example of option negotiation is agreeing upon the terminal emulation (e.g. vt100, xterm, dumb) to use in the Telnet session.

Option negotiation as its name implies is optional and may be initiated by either the client or server. This does not mean however that option negotiation may be ignored. For example, in the event that the server attempts to perform option negotiation the client must respond by either accepting or rejecting the option request. Capturing option negotiation data from the Telnet server is accomplished using the TelnetListener class. In order to capture this data you must register an instance of the TelnetListener class with the Telnet instance as shown earlier.

In performing option negotiation there are four (5) Telnet protocol commands that can be used by the client and server.

1.  DO OPTION - Requests to enable an option.
2.  DONT OPTION - Refuses offer to enable an option.
3.  WILL OPTION - Offers to enable an option.
4.  WONT OPTION - Refuses request to enable an option.
5.  SUB OPTION - For option subnegotiation

For the purposes of this article we will refuse all options both requested and offered by the Telnet server. This in effect will give us a basic Telnet client that is capable of exchanging data with the Telnet server. In order to capture and refuse options requested or offered by the Telnet server you will need to overload the TelnetListener#doOption and TelnetListener#willOption methods as follows:

public void doOption(DoOptionEvent event) {
  // refuse any options requested by Telnet server
  telnet.sendWontOption(event.getOption());   
}

public void willOption(WillOptionEvent event) {
  // refuse any options offered by Telnet server
  telnet.sendDontOption(event.getOption());
}

Receiving data

Once option negotiation has been completed you may receive data sent by the Telnet server. To receive data, overload the TelnetListener#dataReceived method as follows:

public void dataReceived(TelnetDataReceivedEvent event) {
  // print data received from Telnet server to console
  System.out.println(event.getData());
}

Sending data

To send data to the Telnet server you will first obtain an OutputStream from the Telnet instance. Given this OutputStream you can then send data to the Telnet server as follows:

// sends all data entered at console to Telnet server
while ((input = reader.readLine()) != null) {
  if (connected) {
    ((TelnetOutputStream) output).println(input);
  } else {
    break;
  }
}

In the example above the input comes from the console and is redirected to the Telnet server using the TelnetOutputStream#println method. The TelnetOutputStream class is used as it automatically appends a \r\n (carriage return line feed) to the end of the data sent. This is required by the Telnet server for it to know when it may begin processing the data received.

Releasing a connection

To release an established connection simply invoke the Telnet#disconnect method as follows:

telnet.disconnect();

Example

Below is the fully functional source code for an interactive Telnet client written using the SSH Factory Telnet component.

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.IOException;
import java.io.OutputStream;

import com.jscape.inet.telnet.DoOptionEvent;
import com.jscape.inet.telnet.Telnet;
import com.jscape.inet.telnet.TelnetAdapter;
import com.jscape.inet.telnet.TelnetConnectedEvent;
import com.jscape.inet.telnet.TelnetDataReceivedEvent;
import com.jscape.inet.telnet.TelnetDisconnectedEvent;
import com.jscape.inet.telnet.TelnetException;
import com.jscape.inet.telnet.TelnetOutputStream;
import com.jscape.inet.telnet.WillOptionEvent;

public class TelnetTutorial extends TelnetAdapter {

   private Telnet telnet = null;
   private OutputStream output = null;
   private static BufferedReader reader = null;
   private boolean connected = false;

   public TelnetTutorial(String hostname)
      throws IOException,
             TelnetException
   {

      String input = null;
      // create new Telnet instance
      telnet = new Telnet(hostname);

      // register this class as TelnetListener
      telnet.addTelnetListener(this);

      // establish Telnet connection
      telnet.connect();
      connected = true;

      // get output stream
      output = telnet.getOutputStream();

      // sends all data entered at console to Telnet server
      while ((input = reader.readLine()) != null) {
         if (connected) {
            ((TelnetOutputStream) output).println(input);
         } else {
            break;
         }
      }
   }

   /** Invoked when Telnet socked is connected.
    * @see TelnetConnectedEvent
    * @see Telnet#connect
    */
   public void connected(TelnetConnectedEvent event) {
      System.out.println("Connected");
   }

   /**
    * Invoked when Telnet socket is disconnected. Disconnect can
    * occur in many circumstances including IOException during socket read/write.
    * @see TelnetDisconnectedEvent
    * @see Telnet#disconnect
    */
   public void disconnected(TelnetDisconnectedEvent event) {
      connected = false;
      System.out.print("Disconnected.  Press enter key to quit.");
   }

   /**
    * Invoked when Telnet server requests that the Telnet client begin performing specified <code>TelnetOption</code>.
    * @param event a <code>DoOptionEvent</code>
    * @see DoOptionEvent
    * @see TelnetOption
    */
   public void doOption(DoOptionEvent event) {
      // refuse any options requested by Telnet server
      telnet.sendWontOption(event.getOption());
   }

   /**
    * Invoked when Telnet server offers to begin performing specified <code>TelnetOption</code>.
    * @param event a <code>WillOptionEvent</code>
    * @see WillOptionEvent
    * @see TelnetOption
    */
   public void willOption(WillOptionEvent event) {
      // refuse any options offered by Telnet server
      telnet.sendDontOption(event.getOption());
   }

   /**
    * Invoked when data is received from Telnet server.
    * @param event a <code>TelnetDataReceivedEvent</code>
    * @see TelnetDataReceivedEvent
    */
   public void dataReceived(TelnetDataReceivedEvent event) {
      // print data recevied from Telnet server to console
      System.out.print(event.getData());
   }

   /**
    * Main method for launching program
    * @param args program arguments
    */                                                              
   public static void main(String[] args) {
      try {
         reader = new BufferedReader(new InputStreamReader(System.in));

         // prompt user for Telnet server hostname
         System.out.print("Enter Telnet server hostname (e.g. 10.0.0.1): ");
         String hostname = reader.readLine();

         // create new TelnetTutorial instance
         TelnetTutorial tutorial = new TelnetTutorial(hostname);

      } catch (Exception e) {
         e.printStackTrace(System.out);
      }
   }

}

Download the source code here: TelnetTutorial.java

Summary

In this article you learned how to establish an interactive Telnet session with a Telnet server using the Telnet component provided in both SSH Factory and Secure iNet Factory. The Telnet component in both SSH Factory and Secure iNet Factoryy makes this easy removing the complexities of the Telnet protocol.

References

Telnet Class Overview
Telnet Class Javadoc
Telnet Wiki

Sending HTML Based Email using Java

Overview

This article will demonstrate how using Secure iNet Factory components you can compose an email message that can be displayed by both HTML capable and plain-text only email clients.

To see what else Secure iNet Factory has to offer Download a FREE 30 day Secure iNet Factory Evaluation.

Overview of HTML email

The use of HTML is becoming an increasingly popular format for the communication of messages via email. Largely contributing to the success of HTML based messages is that a majority of users now use HTML capable email. clients. Such popular email clients include Microsoft Outlook, Netscape Communicator and Qualcomm Eudora just to name a few.

Benefits of HTML email

Unlike its plain text counterpart, an HTML email message can include elements such as images, hyperlinks and even web forms. This is a clear benefit to those developing collaborative applications that rely on email.

Problems sending HTML email

Although many users have HTML capable email clients, there are still a large number of users that do not. This for the most part includes a number of universities and large corporations that still rely on text-based email clients. Without support for HTML in the email client how can you ensure that the recipient of an HTML email message can read it in its intended form? To begin let's start with the basic format of email.

Plain-text email

To: recipient@domain.com
From: sender@domain.com
Subject: Plain Text email.
Content-Type: text/plain; charset="us-ascii"

This is plain text

The example above shows a message in plain text format Notice the Content-Type header. The header indicates to an email client the contents of this message are in plain text (text/plain) and uses the US ASCII (us-ascii) character set.

HTML email

To: recipient@domain.com
From: sender@domain.com
Subject: HTML email.
Content-Type: text/html; charset="us-ascii"

<b>This is HTML text</b>

The example above shows a message in HTML format. Notice again the Content-Type header. The header indicates to an email client that the contents of this message are in HTML (text/html) and uses the US ASCII (us-ascii) character set. Also notice the opening and closing <b> HTML tags used in the body of the message.

An HTML capable email client reading this message would know that based on the Content-Type header, to display any HTML markup within the body of the message as rendered HTML. Had the Content-Type header used a value of text/plain instead of text/html then the mail client would have simply displayed the message including any HTML source (non-rendered). Similarly, had a plain-text only client read this message it would have displayed the message including any HTML source. To solve this problem lets look at creating a multipart email.

Multipart email

Date: Tue, 01 Jul 2003 09:48:30 -0700
MIME-Version: 1.0
Message-ID: <2.4.1057078110032@localhost>
Content-Transfer-Encoding: quoted-printable
Content-Type: multipart/mixed; charset=us-ascii;
  boundary=___BoUnDaRy_1057078110032.797.291273273055
From: sender@domain.com
To: recipient@domain.com
Subject: multipart mixed email.

--___Boundary_1057078110032.797.291273273055
Content-Type: multipart/alternative;
  boundary=___Boundary_1057078110032.355.65337159541633

--___Boundary_1057078110032.355.65337159541633
Content-Type: text/plain

This is plain text

--___Boundary_1057078110032.355.65337159541633
Content-Type: text/html

<b>This is HTML text</b>
--___Boundary_1057078110032.355.65337159541633--

--___Boundary_1057078110032.797.291273273055--

The above is an example of a multipart email. Notice the first Content-Type header. This header indicates to an email client that the message has multiple parts. The second Content-Type header indicates that the message parts are varied in format (multipart/alternative). Given the multipart/alternative Content-Type header, the email client will display the format most suited to its environment, HTML for HTML capable clients, plain-text for text only clients or a suitable error message for email clients that are incapable of reading MIME messages (very unlikely). This format is clearly a solution to our problem as it provides formats which can be viewed on virtually any mail client within a single email message.

The following code snippet demonstrates how to create a multipart email like the one described above.

//import the necessary classes
import com.jscape.inet.smtp.Smtp;
import com.jscape.inet.email.EmailMessage;
import com.jscape.inet.mime.MimeMessage;

...

      String from = "sender@domain.com";
      String to = "recipient@domain.com";
      String subject = "multipart mixed email.";
      String plainText = "This is plain text";
      String htmlText = "<b>This is HTML text</b>";

      try {
         EmailMessage email = new EmailMessage();
         email.setContentType("multipart/mixed");
         // create email message
         email.setFrom(from);
         email.setTo(to);
         email.setSubject(subject);

         MimeMessage contents = new MimeMessage();
         contents.setContentType("multipart/alternative");

         try {
            MimeMessage plainMessage = new MimeMessage();
            plainMessage.setContentType("text/plain");
            plainMessage.setBody(plainText);
            contents.addPart(plainMessage);
         } catch (Exception e) {
            System.out.println(e);
         }

         try {
            MimeMessage htmlMessage = new MimeMessage();
            htmlMessage.setContentType("text/html");
            htmlMessage.setBody(htmlText);
            contents.addPart(htmlMessage);
         } catch (Exception e) {
            System.out.println(e);
         }
         email.addPart(contents);          

         Smtp smtp = new Smtp("smtp.west.cox.net");
         smtp.setDebug(true);
         smtp.connect();
         smtp.send(email);
         smtp.disconnect();
      }
      catch (Exception e) {
         e.printStackTrace();
      }

Download the full source code here: SmtpMultipartTutorial.java

Summary

In this article you learned how to send HTML based email that can be displayed by both HTML and plain-text only email. clients. The SMTP and MIME components in Secure iNet Factory make this easy removing the complexities of the SMTP and MIME protocols.

References

Smtp Class Overview
Smtp Class Javadoc
MimeMessage Class Javadoc
MIME Wiki