name type description String or Component Detach and Termination Attributes. Common to File, Mkdir and TouchFile components name type description

Transcription

1 File s The file components provide a cross platform way of representing files. File Mkdir SelfDeletingFile TempFile TextFile TouchFile Describes a file, with optional liveness checks for existence and type Creates a directory Identifies a file that must be deleted when the application is terminated instantiates a temporary file Saves text to a named file, with optional encoding Sets the timestamp of a file, creating it if needed. Declaring the components The components are implemented in the package org.smartfrog.services.os.filesystem. To use them in a deployment descriptor, This will include the schema and component descriptions ready for use. Attributes Common to most components filename deleteonexit boolean Attribute for those components (SelfDeletingFile, TempFile, TextFile), that can be deleted on termination. URI read only string A file: URI to the file. Equivalent to Detach and Termination Attributes. Common to File, Mkdir and TouchFile components s that support this attributes: File, Mkdir, TouchFile. sfshoulddetach sfshouldterminate sfshouldterminatequietly OptionalBoolean Should the component detach itself from its parent after completing its sfstart livecycle method. OptionalBoolean Should the component terminate itself from its parent after completing its sfstart livecycle method. OptionalBoolean Should the component terminate quietly (it does not notify its parent) when it terminates. All these attributes are optional and can be combined. Example: a component can detach itself and then

2 terminate. These attributes are particularly useful when the components are used in workflows. s File This component represents a file. It does not have any actions at during deployment or termination, other than to 1. Convert the parameters describing the file into a platform specific format. 2. Set the absolutepath and uri attributes, as with other filesystem components 3. Set the other read-only attributes to the state of the file/directory. It can respond to liveness checks by verifying that any declarations about the state of the file still hold. There are three ways of using this component. First, it can be used to identify files to work with. Secondly, it can take existing files, and apply liveness checks to the file. Thirdly, by converting OS operations that query the file into component attributes, it can be used to feed file state information into other components. Writeable attributes filename String Name of a file dir mustexist mustread mustwrite mustbefile mustbedir testonstartup testonliveness Directory OptionalBoolean file must exist OptionalBoolean the process must have read access OptionalBoolean the file must be writeable OptionalBoolean must be a file OptionalBoolean must be a directory OptionalBoolean verify state of file during startup OptionalBoolean verify state of file in liveness checks It also supports OptionalBoolean attributes: sfshoulddetach, sfshouldterminate and sfshouldterminatequietly.see Detach and Terminate Attributes section. Read-only attributes exists Boolean true iff the file exists isfile Boolean true if the file is isdirectory Boolean true if the file is a directory ishidden Boolean true if the file is timestamp long timestamp of the file, -1 if the file is not present length long length of file (0 if the file is not present) isempty Boolean true if the file is of length zero (or implicitly: does not exist)

3 SelfDeletingFile This component deletes a file when it is terminated. If the file does not exist, or the deleteonexit flag is not set to true, this does not take place. filename deleteonexit Boolean Attribute for those components (SelfDeletingFile, TempFile, TextFile), that can be deleted on termination. TempFile This component names a temporary file. prefix String prefix should be three or more characters long suffix OptionalString suffix, like ".tmp" dir OptionalString a directory. If not specified, the temp directory for this JVM will be used. deleteonexit Boolean Attribute for those components (SelfDeletingFile, TempFile, TextFile), that can be deleted on termination. TextFile filename deleteonexit Boolean Request deletion on termination.

4 encoding string Text encoding to use (default="utf8") text string Text to write When a TextFile component is deployed, it fills in the nominated file with the contents of the text attribute, using whatever encoding is requested. The file will be deleted at termination, if deleteonexit is set. TouchFile This component touches a file. if the file does not exist, it is created. A timestamp can be passed in as seconds since , or -1 for "latest time". temp1 extends TempFileWithCleanup { deleteonexit true; prefix "temp1"; suffix ".txt"; assert extends Assert { fileexists LAZY temp1:filename; touch extends TouchFile { filename PARENT:filename; timestamp PARENT:timestamp; //the filename filename LAZY temp1:absolutepath; //and timestamp timestamp L; It also supports OptionalBoolean attributes: sfshoulddetach, sfshouldterminate and sfshouldterminatequietly.see Detach and Terminate Attributes section. Mkdir This component creates a directory when deployed. All necessary parent directories are auto-created. dir parent Optional Parent directory. Optional absolutepath read only string the absolute, platform specific path of the directory. uri read only string A file: URI to the directory. Equivalent to It also supports OptionalBoolean attributes: sfshoulddetach, sfshouldterminate and sfshouldterminatequietly.see Detach and Terminate Attributes section.

5 Example: Mkdir #include "/org/smartfrog/services/assertions/components.sf" newdir LAZY mkdir:absolutepath; mkdir extends Mkdir { parent LAZY PROPERTY java.io.tmpdir; dir "/new-directory-for-mkdir"; assert extends Assert { direxists PARENT:newdir; This example creates a temporary directory under the parent directory ${java.io.tmpdir, then asserts that it has been created. Note the use of LAZY PROPERTY reference when extracting this value. If the non-lazy property were used, the parent attribute would be set to the temporary directory of the JVM/Process which parsed the deployment descriptor, not the process which actually deployed the component. When deploying to a remote system, the difference can be significant. Although "/" is used as the directory separator, this descriptor is still valid on Windows systems, and other platforms with alternate path separators. The directory attribute will have / and \ characters converted to the local platform's type during deployment. The target platform is not an issue with the file types, although the value of the absolutepath attribute will be different for the different systems. Limitations of the components 1. Because Java has no explicit access to file system permissions, SmartFrog components cannot create files with access rights other than the default for the Java process. 2. There is not (yet) an rmdir component, to delete a directory. Examples Example: temporary text file This is a temporary text file that is deleted after termination #include "/org/smartfrog/services/assertions/components.sf" temp1 extends TempFile { deleteonexit true; prefix "temp1"; suffix ".txt"; assert extends Assert { fileexists LAZY temp1:absolutepath; textfile extends TextFile { file LAZY temp1; text "Here is some text that we want to use in our document"; //the filename absolutepath LAZY textfile:absolutepath; //the uri uri LAZY textfile:uri;

6 The temp1 component names and creates a temporary file in the system's temporary directory. The text file component then fills this in with some text of our choice, in the default (UTF8) encoding. The assert component verifies that the file exists; The absolutepath attribute in the root component is LAZY bound to the value of the textfile. This component is not explicitly set, but is implicitly set when the component binds to the file component. This happens at deployment time. The uri attribute is similar. Because the temp1 file is already marked as deleteonexit, there is no need to indicate this in the textfile declaration, though to do so should be harmless. We say should, as the sole risk is that during undeployment, after temp1 deletes the file a new file may be created with the same name as is about to be deleted, a file that textfile may then unwittingly delete. This is a possible, albeit unlikely race condition. Example2: encoded text file This example uses a different text encoding, and an alternate cleanup mechanism temp1 extends TempFile { prefix "encoded"; suffix ".txt"; cleanup extends SelfDeletingFile { file LAZY temp1; textfile extends TextFile { file LAZY temp1; text "UTF16"; encoding "UTF-16"; //the filename absolutepath LAZY textfile:absolutepath; //the uri uri LAZY textfile:uri; Here, a SelfDeletingFile is used to clean up the file at termination time. Using the filesystem components in other components The goal of these tasks is to make it easy to name files in a cross platform manner. Here are the ways to do this. Extend FileUsingImpl This class has support code for the core writeable attributes (file, deleteonexit), and those that are set at runtime (absolutepath, uri). To use the features 1. extend the class FileUsingImpl. 2. In sfdeploy() or later, bind to a filename. 3. If deleteonexit is to be supported, call deletefileifneeded() during termination. 4. Implement any other interfaces or operations that are desired. Note that the methods of FileIntf and UriIntf are already implemented. To bind to a filename use bind(file) to set the runtime attributes, and set the file member variable, a variable that can be accessed via getfile();

7 Use bind(boolean mandatory,string defval) to force the filename attribute to be read, converted from a File instance or a string path into an absolute path, and then bound to. Determine the file name as a string, and use setabsolutepath(string) to bind the component to a path. Use static helper methods in FileSystem There are is a static method, lookupabsolutepath(), in the class FileSystem, methods that can resolve any attribute of a named component, and then either convert its string value into a local pathname, or resolving it to a FileIntf interface, ask for the path with a call to getabsolutepath(). The resolveabsolutepath() method does the same, except it returns a File instance. The FileSystem class also includes helper methods to close input and output streams quietly, without throwing an IO exception, and checking for null parameters. These should be used in exception handlers, to quietly close streams on failure. They should not be used in the main body of a method, as there may be a valid reason for a close operation to fail (such as a full filesystem), valid reasons that should be propagated. Consult the Javadoc documentation for details on how to use these method. It can be used from any component that needs to resolve pathnames.