org.sandev.basics.util
Interface UIFileLocator

All Known Subinterfaces:

UIFormAdaptorCallback, UIFormOwner

public interface UIFileLocator

Provide file and URL access to uploaded or generated files. This interface provides a general mechanism for locating a standard file output area (such as for reports) and standard file input area (such as for file import processing). More advanced input and output processing can be created using mapped subdirectories.

The application may be running locally or remotely, and both input and output files will need to be referenced via URL to allow for viewing through the application at runtime (even a standalone GUI still has links). The format of this URL can vary with the deployment environment, leaving an implementing class having to make decisions about where to find files for different environments. Here's how this works:

1. On initialization, the UI determines whether it is running in a local environment. If running locally, then it calls getInboundFilesDir and builds a link URL using the returned file specification. Otherwise it builds a URL from the incoming request. After establishing an expected inbound URL link, the UI calls setInboundFilesLink with that value. This call happens only once at initialization, and provides a working default value for linking to uploaded files.
2. When a file is specified for upload, it is assigned a unique name and written to
   new File(uifl.getInboundFilesDir() + filename)
   It is up to the implementing class to provide a working directory specification here.
3. When rendering a link to an uploaded file reference, the UI calls getInboundFilesLink to get the base URL for where to find the uploaded file. Some example return values:

   http://sandservices.com/uploads/	Remote static content area created from expected base URL.
   file:///C:/appdir/uploads/	Local static content area created from expected base URL.
   http://thisapp/Main?class=UploadFileRef&file=	Dyanamic content rendering (same format for either local or remote, file found and rendered by UploadFileRef lookup processing).

Example 1, Remapped local path specification:

• getInboundFilesDir returns TaskHeap/uploads/
• On a deployment machine, /tomcat/bin/TaskHeap/uploads (or the equivalent) is symlinked to /www/uploads which is backed up nightly.
• On a development machine with the application running locally, the uploaded file is found using using a file access URL.

Example 2, Development box override:

• If the TASKHEAP_UPLOAD_DIRECTORY environment variable is found, then getInboundFilesDir returns that value, otherwise it returns www/uploads/
• On a deployment machine, the file is written to the static content webserver area where it is accessible and backed up.
• On a development machine, the file is written to the specified directory and the uploaded file is found using a file access URL.

Outbound file processing is analogous.

If an application does not require inbound (upload) file processing, and does not generate any outbound files, then the rendering methods are not used and can be stubbed.

Method Summary

java.lang.String	getInboundFilesDir() Return the directory where inbound files should be written to.
java.lang.String	getInboundFilesLink() Return the base link specification used for inbound files.
java.lang.String	getOutboundFilesDir() Return the directory where outbound files are written to.
java.lang.String	getOutboundFilesLink() Return the base link specification used for outbound files.
void	setInboundFilesLink(java.lang.String defaultInboundFilesLink) Called by the rendering during setup with the default URL where inbound files are expected to be found.
void	setOutboundFilesLink(java.lang.String defaultOutboundFilesLink) Called by the rendering during setup with the default URL where outbound files are written.

Method Detail

setInboundFilesLink

public void setInboundFilesLink(java.lang.String defaultInboundFilesLink)

Called by the rendering during setup with the default URL where inbound files are expected to be found.

getInboundFilesDir

public java.lang.String getInboundFilesDir()

Return the directory where inbound files should be written to. The return value must be a valid directory specification for the current operating environment. If the directory does not exist, then it will be created as needed.

getInboundFilesLink

public java.lang.String getInboundFilesLink()

Return the base link specification used for inbound files. After a file has been uploaded or imported to the directory specified by getInboundFilesDir, the UI may need to display a link to this uploaded file. This method returns the link text up to but not including the filename.

setOutboundFilesLink

public void setOutboundFilesLink(java.lang.String defaultOutboundFilesLink)

Called by the rendering during setup with the default URL where outbound files are written.

getOutboundFilesDir

public java.lang.String getOutboundFilesDir()

Return the directory where outbound files are written to. The return value must be a valid directory specification for the current operating environment. If the directory does not exist, then it will be created as needed.

getOutboundFilesLink

public java.lang.String getOutboundFilesLink()

Return the base link specification used for outbound files. After a file has been written to the directory specified by getInboundFilesDir, the UI may need to display a link to this uploaded file. This method returns the link text up to but not including the filename.