Node Monitor v0.6.5

Show:

FileProbe Class

Extends Probe
Defined in: lib/probes/FileProbe.js:28
Module: Probes

Probe for monitoring a file on the O/S.

This probe monitors a file for changes. It can either contain the full file contents, or the most recent file changes.

For security purposes, this probe is disabled by default. The application server must set the root directory path using setRootPath() before the probe will operate.

To enable FileProbe on the server:

// Enable the File probe under the user home directory
var Monitor = require('monitor');
Monitor.FileProbe.setRootPath('/home/public');

This class also contains server-side utility methods for file and directory manipulation.

Using the FileProbe (client or server):

// Watch the template for changes
var indexTemplate = new Monitor({
  probeClass: 'File',
  initParams: {
    path: 'templates/index.html'
  }
});
indexTemplate.connect(function(error) {
  console.log("Connected");
});

Once connected, the text field of indexTemplate will be set to the file contents, and the change listener will fire whenever the server detects a change in the template file.

Constructor

FileProbe

(
  • initParams
  • model
)

Parameters:

  • initParams Object

    Remote initialization parameters

    • path String

      Path to the file beneath the server-specified root path.

    • [tail=false] Boolean optional

      false:text contains current file content, true: text contains last changes.

  • model Object

    Monitor data model elements

    • text String

      Full file contents, or last file changes.

    • error String

      File read errors.

Item Index

Methods

Methods

getRootPath

() String static

Get the current root path.

As a static method, this is only available on the server running the probe. For security purposes, this is not exposed in the FileProbe data model.

Returns:

String: The path to the root directory for the FilePath probe

initialize

(
  • attributes
  • options
)

Inherited from Probe:

Initialize the probe

This is called on the probe during construction. It contains the probe initialization attributes and an option to make probe construction asynchronous.

Probe implementations can defer the initial response to the monitor until the initial state is loaded. This allows the callback on Monitor.connect() to have the complete initial state of the probe when called.

If the initial probe state cannot be determined in initialize, it should set the options.asyncInit option to true, and call the options.callback(error) once the initial state is determined.

// Asynchronous initialization
options.asyncInit = true;
var callback = options.callback

If asyncInit is set to true, the callback must be called once the initial state of the probe is known (or in an error condition).

// Set the initial state, and call the callback
this.set(...);
callback(null);

See the initialize method of the FileProbe probe for an example. It defers returning the probe to the monitor until the initial file contents are loaded.

Parameters:

  • attributes Object

    Initial probe attributes sent in from the Monitor

  • options Object

    Initialization options

    • asyncInit Boolean

      Set this to TRUE if the initial probe state can't be known immediately.

    • callback Function(error)

      The callback to call if asyncInit is set to true. If an error is passed, the probe will not be used.

mkdir_r

(
  • dirname
  • [mode=0777]
  • [callback]
)
static

Create a directory recursively

This makes a directory and all nodes above it that need creating.

Parameters:

  • dirname String

    Full directory path to be made

  • [mode=0777] Object optional

    Directory creation mode (see fs.mkdir)

  • [callback] Function(error) optional

    Called when complete, with possible error.

onControl

(
  • name
  • [params]
  • [callback]
)

Inherited from Probe:

Dispatch a control message to the appropriate control function.

This is called when the control() method of a monitor is called. The name determines the method name called on the probe.

The probe must implement a method with the name {name}_control(), and that method must accept two parameters - an input params and a callback. The callback must be called, passing an optional error and response object.

For example, if the probe supports a control with the name go, then all it needs to do is implement the go_control() method with the proper signature. See ping_control() for an example.

Parameters:

  • name String

    Name of the control message.

  • [params] Any optional

    Input parameters specific to the control message.

  • [callback] Function(error, response) optional

    Called to send the message (or error) response.

    • error (Any) An object describing an error (null if no errors)
    • response (Any) Response parameters specific to the control message.

ping_control

(
  • params
  • callback
)

Inherited from Probe:

Respond to a ping control sent from a monitor

Parameters:

  • params Object

    Input parameters (not used)

  • callback Function(error, response)

    Called to send the message (or error) response.

    • error (Any) An object describing an error
    • response (String) The string 'pong' is returned as the response

release

()

Inherited from Probe:

Release any resources consumed by this probe.

This can be implemented by derived classes that need to be informed when they are to be shut down.

Probes that listen to events should use this method to remove their event listeners.

rm_rf

(
  • path
  • callback
)
static

Remove a file or directory recursively

This is equivalent to shell rm -rf {filepath or dirpath}.

Parameters:

  • path String

    Path to a directory or file to remove

  • callback Function(error)

    Function to call when done, with possible error.

setRootPath

(
  • rootPath
)
static

Set the server root path for the file probe

For security purposes, this must be set server-side before the File probe will operate. It will not accept any changes once set.

Parameters:

  • rootPath String

    A path to the root directory for the FilePath probe

tail

(
  • path
  • [options]
  • callback
)
Object static

Tail a file

Parameters:

  • path String

    Path to the file

  • [options] Object optional

    File watch options

    • encoding=UTF8 String

      File encoding type.

  • callback Function (content)

    Function called on change

Returns:

Object: An object that contains a close() method to call when done tailing.

watch

(
  • path
  • [options]
  • callback
  • callabck.event
)
Object static

Build a backwards compatible file change watcher

The Node.js fs.watch functionality was introduced in version 0.6.x. This method builds a watcher object that uses the new funcitonality, and degrades to the polling style fs.watchFile functionality if running with node.js that doesn't have fs.watch.

The provided callback is only fired if the file has changed.

When done watching, make sure to call the close() method of the returned object to release resources consumed by file watching.

Parameters:

  • path String

    Path to the file

  • [options] Object optional

    File watch options

    • [persistent=false] Boolean optional

      File encoding type.

    • [pollStyle=false] Boolean optional

      Use the older polling-style watchFile.

    • [interval=10] Integer optional

      Polling interval (if pollStyle=true)

  • callback Function (event)

    Function called on file change.

  • callabck.event String

    One of 'change' or 'rename' (delete = 'rename')

Returns:

Object: An object that contains a close() method to call when done watching.

watchLoad

(
  • path
  • [options]
  • callback
)
Object static

Watch a file for changes and reload the content on change

This method accepts a callback function that is invoked whenever the file contents have changed. If preload is requested, the callback is also called on the initial file contents.

// Monitor the homePage.html template
var FileProbe = Monitor.FileProbe;
var path = __dirname + "/templates/homePage.html";
var options = {preload:true};
var homePageWatcher = FileProbe.watchLoad(path, options, function(error, content) {
  console.log("Home page template: " + content)
});

This uses the Node.js fs.watch functionality if available, or the older polling mechanism if running on a pre-0.6.x version of Node.js.

When done watching, call the close() method of the returned watcher object. This releases all resources associated with file watching.

// Stop watching the homePage template
homePageWatcher.close();

Parameters:

  • path String

    Path to the file

  • [options] Object optional

    File watch options

    • encoding='utf8' String

      File encoding type.

    • preload=false Boolean

      Preload the contents, calling the callback when preloaded.

    • persistent=false Boolean

      Persistent file watching?

  • callback Function (error, content)

    Function called on file change (or error), and on preload if requested.

Returns:

Object: An object that contains a close() method to call when done watching.
Copyright © 2010-2014 Loren West, and other contributors. All rights reserved.
Docs generated using YUIDoc JS