Awake File v1.1

org.awakefw.file.api.client
Class AwakeFileSession

java.lang.Object
  extended by org.awakefw.file.api.client.AwakeFileSession
All Implemented Interfaces:
Cloneable

public final class AwakeFileSession
extends Object
implements Cloneable

Main class for executing from a Client (typically a PC) all sorts of operations on remote files or remote classes through a Http or Https session.

Class includes methods to:

Example:
 // Create an AwakeFile instance and username on the remote server
 // using the URL of the path to the AwakeFileManager Servlet
 String url = "https://www.acme.org/AwakeFileManager";
  
 // The login info for strong authentication on server side:
 String username = "myUsername";
 char[] password = { 'm', 'y', 'P', 'a', 's', 's', 'w', 'o', 'r', 'd' };
  
 AwakeFileSession awakeFileSession = new AwakeFileSession(url, username,
        password);
  
 // OK: upload a file
 awakeFileSession.upload(new File("c:\\myFile.txt"), "myFile.txt");
 

Communication via an (authenticating) proxy server is done using a HttpProxy instance:

 HttpProxy httpProxy = new HttpProxy("myproxyhost", 8080);
 String url = "https://www.acme.org/AwakeFileManager";
  
 // The login info for strong authentication on server side:
 String username = "myUsername";
 char[] password = { 'm', 'y', 'P', 'a', 's', 's', 'w', 'o', 'r', 'd' };
  
 AwakeFileSession awakeFileSession = new AwakeFileSession(url, username,
        password, httpProxy);
  
 // Etc.
 
 

All long operations that need to be run on a separated thread may be followed in Swing using a Java Progress Bar or Progress Monitor: just implement the AwakeProgressManager interface.

Since:
1.0
See Also:
HttpProxy, AwakeProgressManager

Constructor Summary
AwakeFileSession(String url, String username, char[] password)
          Creates an AwakeFile session.
AwakeFileSession(String url, String username, char[] password, HttpProxy httpProxy)
          Creates an AwakeFile session with a proxy.
AwakeFileSession(String url, String username, char[] password, HttpProxy httpProxy, HttpProtocolParameters httpProtocolParameters)
          Creates an AwakeFile session with a proxy and protocol parameters.
 
Method Summary
 String call(String methodName, Object... params)
          Calls a remote Java class.method and (eventually) pass some parameters to it.
 AwakeFileSession clone()
          Allows to get a copy of the current AwakeFileSession: use it to do some simultaneous operations in a different thread (in order to avoid conflicts).
 boolean delete(String remoteFile)
          Deletes a remote file or remote directory on the host.
 void download(String remoteFile, File file)
          Downloads a file from the remote server.
 boolean exists(String remoteFile)
          Says if a remote file or directory exists.
 String getAuthenticationToken()
          Returns the Authentication Token.
 AwakeProgressManager getAwakeProgressManager()
          Returns the AwakeProgresManager in use.
 HttpProtocolParameters getHttpProtocolParameters()
          Returns the HttpProtocolParameters instance in use for the Awake File session.
 HttpProxy getHttpProxy()
          Returns the HttpProxy instance in use for this Awake session.
 int getHttpStatusCode()
          Returns the http status code of the last executed verb
 String getUrl()
          Returns the URL of the path to the AwakeFileManager Servlet (or AwakeSqlManager Servlet if session has been initiated by an AwakeConnection).
 String getUsername()
          Returns the username of this Awake File session
 String getVersion()
          Returns the Awake File Version.
 long length(List<String> remoteFiles)
          Returns the length of a a list of files located on the remote host.
 long length(String remoteFile)
          Returns the length of a file located on the remote host.
 List<String> listDirectories(String remoteFile)
          Lists the sub-directories contained in a remote directory
 List<String> listFiles(String remoteFile)
          Lists the files contained in a remote directory.
 void logoff()
          Logs off from the remote host.
 boolean mkdir(String remoteFile)
          Executes a Java File.mkdir() on the Host.
 boolean mkdirs(String remoteFile)
          Executes a Java File.mkdirs() on the Host.
 void setAwakeProgressManager(AwakeProgressManager awakeProgressManager)
          Allows to set an Awake Progress Manager instance.
static void setUseBase64EncodingForCall()
          Says if we wan to use base64 encoding for parameters passed to call() - This is a method for legacy applications prior to v1.0.
 void upload(File file, String remoteFile)
          Uploads a file on the server.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AwakeFileSession

public AwakeFileSession(String url,
                        String username,
                        char[] password)
                 throws MalformedURLException,
                        UnknownHostException,
                        ConnectException,
                        InvalidLoginException,
                        RemoteException,
                        IOException,
                        SecurityException
Creates an AwakeFile session.

Parameters:
url - the URL of the path to the AwakeFileManager Servlet
username - the username for authentication on the Awake Server (may be null for call()
password - the user password for authentication on the Awake Server (may be null)
Throws:
MalformedURLException - if the url is malformed
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection..
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
InvalidLoginException - the username or password is invalid
SecurityException - Scheme is required to be https (SSL/TLS)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

AwakeFileSession

public AwakeFileSession(String url,
                        String username,
                        char[] password,
                        HttpProxy httpProxy)
                 throws MalformedURLException,
                        UnknownHostException,
                        ConnectException,
                        InvalidLoginException,
                        RemoteException,
                        SecurityException,
                        IOException
Creates an AwakeFile session with a proxy.

Parameters:
url - the URL of the path to the AwakeFileManager Servlet
username - the username for authentication on the Awake Server (may be null for call()
password - the user password for authentication on the Awake Server (may be null)
httpProxy - the http proxy to use (null if none)
Throws:
MalformedURLException - if the url is malformed
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection..
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
InvalidLoginException - the username or password is invalid
SecurityException - Scheme is required to be https (SSL/TLS)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

AwakeFileSession

public AwakeFileSession(String url,
                        String username,
                        char[] password,
                        HttpProxy httpProxy,
                        HttpProtocolParameters httpProtocolParameters)
                 throws MalformedURLException,
                        UnknownHostException,
                        ConnectException,
                        InvalidLoginException,
                        RemoteException,
                        SecurityException,
                        IOException
Creates an AwakeFile session with a proxy and protocol parameters.

Parameters:
url - the URL of the path to the AwakeFileManager Servlet
username - the username for authentication on the Awake Server (may be null for call()
password - the user password for authentication on the Awake Server (may be null)
httpProxy - the http proxy to use (null if none)
httpProtocolParameters - the http parameters to use (may be null)
Throws:
MalformedURLException - if the url is malformed
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection..
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
InvalidLoginException - the username or password is invalid
SecurityException - Scheme is required to be https (SSL/TLS)
RemoteException - an exception has been thrown on the server side. This traps an Awake product failure and should not happen.
IOException - For all other IO / Network / System Error
Method Detail

call

public String call(String methodName,
                   Object... params)
            throws IllegalArgumentException,
                   InvalidLoginException,
                   UnknownHostException,
                   ConnectException,
                   RemoteException,
                   IOException
Calls a remote Java class.method and (eventually) pass some parameters to it.

Parameters:
methodName - the full method name to call in the format org.acme.config.package.MyClass.myMethod
params - the array of parameters passed to the method
Returns:
the result of the Java call as string
Throws:
IllegalArgumentException - if methodName is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

clone

public AwakeFileSession clone()
Allows to get a copy of the current AwakeFileSession: use it to do some simultaneous operations in a different thread (in order to avoid conflicts).

Overrides:
clone in class Object

delete

public boolean delete(String remoteFile)
               throws IllegalArgumentException,
                      InvalidLoginException,
                      UnknownHostException,
                      ConnectException,
                      RemoteException,
                      IOException
Deletes a remote file or remote directory on the host. (Directory must be empty to be deleted).

Parameters:
remoteFile - the file name on the host
Returns:
true if the file has been deleted
Throws:
IllegalArgumentException - if remoteFile is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
SecurityException - the url is not secured with https (SSL)
IOException - For all other IO / Network / System Error

download

public void download(String remoteFile,
                     File file)
              throws IllegalArgumentException,
                     InvalidLoginException,
                     FileNotFoundException,
                     UnknownHostException,
                     ConnectException,
                     RemoteException,
                     IOException
Downloads a file from the remote server.

The path of the remote file name is relative depending on the Awake File configuration on the server. The path may be expressed

Parameters:
remoteFile - the file name on the host
file - the file to create on the Client side
Throws:
IllegalArgumentException - if remoteFile or file is null
InvalidLoginException - the session has been closed by a logoff()
FileNotFoundException - if the remote file is not found on server
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
InvalidLoginException - the session has been closed by a logoff()
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

exists

public boolean exists(String remoteFile)
               throws IllegalArgumentException,
                      InvalidLoginException,
                      UnknownHostException,
                      ConnectException,
                      RemoteException,
                      IOException
Says if a remote file or directory exists.

Parameters:
remoteFile - the file name on the host
Returns:
true if the file or directory exists
Throws:
IllegalArgumentException - if remoteFile is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
SecurityException - the url is not secured with https (SSL)
IOException - For all other IO / Network / System Error

getAuthenticationToken

public String getAuthenticationToken()
Returns the Authentication Token. This method is used by other Awake products (Awake SQL, ...)

Returns:
the Authentication Token

getAwakeProgressManager

public AwakeProgressManager getAwakeProgressManager()
Returns the AwakeProgresManager in use.

Returns:
the AwakeProgresManager in use

getHttpProtocolParameters

public HttpProtocolParameters getHttpProtocolParameters()
Returns the HttpProtocolParameters instance in use for the Awake File session.

Returns:
the HttpProtocolParameters instance in use for the Awake File session

getHttpProxy

public HttpProxy getHttpProxy()
Returns the HttpProxy instance in use for this Awake session.

Returns:
the HttpProxy instance in use for this Awake session

getHttpStatusCode

public int getHttpStatusCode()
Returns the http status code of the last executed verb

Returns:
the http status code of the last executed verb

getUrl

public String getUrl()
Returns the URL of the path to the AwakeFileManager Servlet (or AwakeSqlManager Servlet if session has been initiated by an AwakeConnection).

Returns:
the URL of the path to the AwakeFileManager Servlet

getUsername

public String getUsername()
Returns the username of this Awake File session

Returns:
the username of this Awake File session

getVersion

public String getVersion()
Returns the Awake File Version.

Returns:
the Awake File Version

length

public long length(List<String> remoteFiles)
            throws IllegalArgumentException,
                   InvalidLoginException,
                   UnknownHostException,
                   ConnectException,
                   RemoteException,
                   IOException
Returns the length of a a list of files located on the remote host.

Parameters:
remoteFiles - the list of the files located on the remote host.
Returns:
the total length of the files located on the remote host.
Throws:
IllegalArgumentException - remoteFilesPath is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if the host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

length

public long length(String remoteFile)
            throws IllegalArgumentException,
                   InvalidLoginException,
                   UnknownHostException,
                   ConnectException,
                   RemoteException,
                   IOException
Returns the length of a file located on the remote host.

Parameters:
remoteFile - the file name on the host
Returns:
the length of the file located on the remote host.
Throws:
IllegalArgumentException - if remoteFilesPath is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if the Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

listDirectories

public List<String> listDirectories(String remoteFile)
                             throws IllegalArgumentException,
                                    InvalidLoginException,
                                    UnknownHostException,
                                    ConnectException,
                                    RemoteException,
                                    IOException
Lists the sub-directories contained in a remote directory

Parameters:
remoteFile - the file name of the directory on the host
Returns:
the list of directories in the remote directory. Will be null if the remote directory does not exists. Will be empty if the remote directory exists but has no sub-directories.
Throws:
IllegalArgumentException - if remoteFile is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

listFiles

public List<String> listFiles(String remoteFile)
                       throws IllegalArgumentException,
                              InvalidLoginException,
                              UnknownHostException,
                              ConnectException,
                              RemoteException,
                              IOException
Lists the files contained in a remote directory.

Parameters:
remoteFile - the file name of the directory on the host
Returns:
the list of files in the remote directory. Will be null if the remote directory does not exists. Will be empty if the remote directory exists but has no files.
Throws:
IllegalArgumentException - if remoteFile is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

logoff

public void logoff()
Logs off from the remote host.  This will purge the authentication values necessary for method calls.

Method should be called at the closure of the Client application.


mkdir

public boolean mkdir(String remoteFile)
              throws IllegalArgumentException,
                     InvalidLoginException,
                     UnknownHostException,
                     ConnectException,
                     RemoteException,
                     IOException
Executes a Java File.mkdir() on the Host.

Parameters:
remoteFile - the file name on the host
Returns:
true if the mkdir() is successful
Throws:
IllegalArgumentException - if remoteFile is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
IOException - For all other IO / Network / System Error
RemoteException

mkdirs

public boolean mkdirs(String remoteFile)
               throws IllegalArgumentException,
                      InvalidLoginException,
                      UnknownHostException,
                      ConnectException,
                      RemoteException,
                      IOException
Executes a Java File.mkdirs() on the Host.

Parameters:
remoteFile - the file name on the host
Returns:
true if the mkdirs() is successful
Throws:
IllegalArgumentException - if remoteFile is null
InvalidLoginException - the session has been closed by a logoff()
UnknownHostException - if host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
IOException - For all other IO / Network / System Error
RemoteException

setAwakeProgressManager

public void setAwakeProgressManager(AwakeProgressManager awakeProgressManager)
Allows to set an Awake Progress Manager instance.

Parameters:
awakeProgressManager - the Awake Progress Manager instance

setUseBase64EncodingForCall

public static void setUseBase64EncodingForCall()
Says if we wan to use base64 encoding for parameters passed to call() - This is a method for legacy applications prior to v1.0.


upload

public void upload(File file,
                   String remoteFile)
            throws IllegalArgumentException,
                   InvalidLoginException,
                   FileNotFoundException,
                   UnknownHostException,
                   ConnectException,
                   RemoteException,
                   IOException
Uploads a file on the server.

The path of the remote file name is relative depending on the Awake File configuration on the server.

Parameters:
file - the file to upload
remoteFile - the file name on the host
Throws:
IllegalArgumentException - if file or remoteFile is null
InvalidLoginException - the session has been closed by a logoff()
FileNotFoundException - if the file to upload is not found
UnknownHostException - if Host url (http://www.acme.org) does not exists or no Internet Connection.
ConnectException - if the Host is correct but the AwakeFileManager Servlet is not reachable (http://www.acme.org/AwakeFileManager) and access failed with a status != OK (200). (If the host is incorrect, or is impossible to connect to - Tomcat down - the ConnectException will be the sub exception HttpHostConnectException.)
RemoteException - an exception has been thrown on the server side
IOException - For all other IO / Network / System Error

Awake File v1.1

Copyright © 2012 Kawan Softwares SAS