WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:Filesystem Accessor
Description:access filesystem resources
Id:layer1.FileScheme
Category:accessor
Identifier Syntax

Filesystem Accessor is an accessor using a standard identifier grammar:

<grammar>
  <group>
    <group name="file">file:
      <regex>.*</regex>
    </group>
  </group>
</grammar>

with the following arguments: (for more details on argument passing details see here)

ArgumentRulesTypingDescription
fileString (unknown)(no description available)
Request Verbs

The following verbs are supported:

Verbs
SOURCESINKEXISTSDELETENEW
Response

The response representation of this accessor for SOURCE requests is unknown.

This accessor throws no documented exceptions.

Import Requirements

To use Filesystem Accessor accessor you must import the module urn:com:1060research:www3:

<import>
  <uri>urn:com:1060research:www3</uri>
</import>

Details

The file: scheme supports high-level access to the file system of the underlying computer and its operating system that hosts the NetKernel platform.

Syntax

The syntax for the scheme is:

Resource Identifier Syntax

file: {path} + {filename}

"file:" + {path} + {filename}

If a directory is to be identified it must include only the path portion and must end with a "/" (slash) character.

For example, the URI:

file:/home/rsk/data/plans.txt

refers to the file plans.txt located in the directory /home/rsk/data/ while the URI:

file:/home/rsk/data/

refers to the directory /home/rsk/data/.

Windows

On Windows we're sorry to say your operating system doesn't have the elegance of a clean filesystem abstraction. You therefore have to use a more complex, fully defined file URI such as...

file:///C:\path\to\my\file.txt

SOURCE

When a request with the SOURCE verb is issued to the file: scheme the contents of the specified file found on the underlying file system of the computer hosting the NetKernel platform is returned as a org.netkernel.layer0.representation.IReadableBinaryStreamRepresentation object.

If the specified file does not exist then a java.io.FileNotFoundException is thrown.

Example

In the following example the contents of a file are requested as a String class. (Note: because the verb SOURCE is the default, it is not necessary to explicitly call the setVerb() method.)

import org.netkernel.layer0.nkf.INKFRequestReadOnly;
// ...
request.context.createRequest("file:/home/rsk/data/temp.txt");
request.setRepresentationClass(String.class);
fileContents = context.issueRequest(request);

SINK

When a request with the SINK verb is issued to the file: scheme the provided representation is serialized to and completely replaces the contents of the specified file in the underlying file system of the computer hosting the NetKernel platform. The supplied representation must be an object of the class org.netkernel.layer0.representation.IBinaryStreamRepresentation, a sub-class or a representation that can be transrepted to that class.

The response contains no representation (null). It is not possible to issue the SINK request to a directory; if that is attempted then a java.io.FileNotFoundExcpetion is thrown.

If the full directory path or file does not already exist, the full path and the file are created before the new contents are serialized.

Example

The following example SINKs the text "File contents" to a designated file. The primary argument is set to a String object which will be implicitly transrepted to a IBinaryStreamRepresentation by the StringSerializer transreptor.

import org.netkernel.layer0.nkf.INKFRequestReadOnly;
// ...
request.context.createRequest("file:/home/rsk/data/temp.txt");
request.addPrimaryArgument("File contents");
request.setVerb(INKFRequestReadOnly.VERB_SINK);
context.issueRequest(request);

NEW

When a request with the NEW verb is issued to the file: scheme a new, empty file or directory is created in the underlying file system of the computer hosting the NetKernel platform.

The response contains a boolean value of either true or false indicating if the file or directory was created. If the file specified by the identifier already exists the the result contains false

Example

The following example creates an empty file temp.txt:

import org.netkernel.layer0.nkf.INKFRequestReadOnly;
// ...
request.context.createRequest("file:/home/rsk/data/temp.txt");
request.setVerb(INKFRequestReadOnly.VERB_NEW);
context.issueRequest(request);

EXISTS

When a request with the EXISTS verb is issued to the file: scheme a test is made for the existence of a file or directory in the physical file system of the computer hosting the NetKernel platform.

The response contains a boolean value of either true or false indicating if the file or directory exists or not.

Example

import org.netkernel.layer0.nkf.INKFRequestReadOnly;
// ...
request.context.createRequest("file:/home/rsk/data/temp.txt");
request.setVerb(INKFRequestReadOnly.VERB_EXISTS);
boolean fileExists = (Boolean)context.issueRequest(request);

DELETE

When a request with the DELETE verb is issued to the file: scheme either a file or a directory in the physical file system of the computer hosting the NetKernel platform is deleted.

The response contains a boolean value of either true or false indicating if the operation succeeded or failed. If a request to DELETE a directory is issued and the directory is not empty the delete will fail and the response will contain false.

Example

The following code deletes a file from the underlying file system. The returned representation indicates if the deletion was successful or not.

import org.netkernel.layer0.nkf.INKFRequestReadOnly;
// ...
request.context.createRequest("file:/home/rsk/data/temp.txt");
request.setVerb(INKFRequestReadOnly.VERB_DELETE);
boolean fileDeleted = (Boolean)context.issueRequest(request);

The following code deletes a directory from the underlying file system. The directory must be empty. The returned representation indicates if the deletion was successful or not.

import org.netkernel.layer0.nkf.INKFRequestReadOnly;
// ...
request.context.createRequest("file:/home/rsk/data/");
request.setVerb(INKFRequestReadOnly.VERB_DELETE);
boolean directoryDeleted = (Boolean)context.issueRequest(request);

Poll Period

By default SOURCE and EXISTS requests for a file: will have caching dependencies which depend on the underlying file resource - however it is potentially expensive to monitor files in realtime for changes - therefore by default the expiry is polled based upon the system-wide file polling interval specified in the kernel.properties (and which may be set as "Filesystem Poll" with the kernel config tool).

Any use of cached file resources in a time period shorter than the poll-period may potentially yield inconsistent results.

If your application requires very precise correlation with the realtime state of a file you may provide the file-poll-period request header and declare a specific poll period with the request. For example, this request has a zero poll period and so will be checked immediately every time its expiry needs to be determined...

req=context.createRequest("file:/tmp/foo");
req.setVerb(INKFRequestReadOnly.VERB_EXISTS);
req.setHeader("file-poll-period", "0");
boolean first=context.issueRequest(req);

file-poll-period must be either a java.lang.Long or a java.lang.String expressing the poll period.