module RSence::Plugins::PluginBase

This module contains common functionality included in the {Plugin__ Plugin}, {GUIPlugin__ GUIPlugin} and the {Servlet__ Servlet} base classes.

Extension hooks for server events

These methods are provided as the basic server event hooks:

Utility methods

These are general utility methods not intended to be extended.

See also

Attributes

plugins[R]

@private External accessor for @plugins @return [PluginManager] The PluginManager the instance belongs to.

Public Instance Methods

bundle_path( path=false, prefix=false, suffix=false ) click to toggle source

Path utility

Makes a full, absolute path using the plugin bundle as the default path when a relative path is given. Returns just the bundle’s local path, if no parameters given.

@param [String, false] path The path is relative to the bundle path by default, unless it starts with ‘/’ or ‘..’. @param [String, false] prefix Alternative root path if path is specified as a relative path. @param [String, false] suffix The file suffix, like the the extension.

@return [String] Full absolute path.

# File lib/rsence/plugins/plugin_base.rb, line 187
def bundle_path( path=false, prefix=false, suffix=false )
  return @path if not path
  if suffix
    path = "#{path}#{suffix}" unless path.end_with?(suffix)
  end
  if prefix
    path = File.join( prefix, path )
  end
  path = File.expand_path( path, @path )
  return path
end
close() click to toggle source

Extend to close objects like streams and database connections.

It is called by the {PluginManager#unload_bundle PluginManager} when the plugin is about to be destructed, so don’t expect any events after it has been called.

@return [nil]

# File lib/rsence/plugins/plugin_base.rb, line 69
def close
end
file_exist?( path ) click to toggle source

File existence checker

Just a wrapper for File.exist, except it handles the path via bundle_path

@return [false] if the file does not exist. @return [true] if the file exists.

# File lib/rsence/plugins/plugin_base.rb, line 78
def file_exist?( path )
  path = bundle_path( path )
  File.exist?( path )
end
file_read( path ) click to toggle source

File reader utility

Reads the contents of the file given in the path.

@param [String] path The path is relative to the bundle path by default, unless it starts with ‘/’ or ‘..’; it’s simply processed by {#bundle_path} before reading the file.

@return [false] If there is no file, returns false @return [String] The contents of the file.

# File lib/rsence/plugins/plugin_base.rb, line 91
def file_read( path )
  path = bundle_path( path )
  return false unless File.exist?( path )
  return File.read( path )
end
file_save( path, data )
Alias for: file_write
file_write( path, data ) click to toggle source

File writer utility.

Writes the contents of the data into the file given in the path. @param [String] path The path is relative to the bundle path by default, unless it starts with ‘/’ or ‘..’; it’s simply processed by {#bundle_path} before writing the file. @param [#to_s] data The data to write.

@return [true,false] A success code of the operation (false for failure and true for success).

# File lib/rsence/plugins/plugin_base.rb, line 155
def file_write( path, data )
  path = bundle_path( path )
  begin
    datafile = File.open( path, 'wb' )
    datafile.write( data.to_s )
    datafile.close
    return true
  rescue => e
    warn "file_write error for path #{path} #{e}"
    return false
  end
end
Also aliased as: file_save
flush() click to toggle source

Extend to save your plugin state, write or flush any data that needs to be stored.

It is called by the {PluginManager#unload_bundle PluginManager} before {#close}, but doesn’t always mean a close event is imminent.

@return [nil]

# File lib/rsence/plugins/plugin_base.rb, line 61
def flush
end
httime(time=false) click to toggle source

Utility for returning the time in the HTTP RFC specification format, like:

!!!text
Sun, 04 Jul 2010 06:20:53 EEST

@param [Time, false] time An Time object to format. Uses the current date/time by default.

@return [String] The date/time formatted according to the HTTP RFC specification.

# File lib/rsence/plugins/plugin_base.rb, line 206
def httime(time=false)
  time = Time.new unless time 
  return time.gmtime.strftime('%a, %d %b %Y %H:%M:%S %Z')
end
init() click to toggle source

Extend this method do any initial configuration instead of extending the initialize constructor, which should never be done in plugins.

It is called by the {PluginManager#register_bundle PluginManager} when the plugin has been constructed and registered.

@return [nil]

# File lib/rsence/plugins/plugin_base.rb, line 45
def init
end
json_read( path ) click to toggle source

JSON reader utility

Reads the contents of the JSON file given in the path and returns as a parsed structure of the contents of the file.

@param [String] path The path is relative to the bundle path by default, unless it starts with ‘/’ or ‘..’; it’s simply processed by {#bundle_path} before reading the file.

@return [false] If the is no file, returns false @return [Object] Any valid structure defined by the YAML file, parsed to a Ruby object.

# File lib/rsence/plugins/plugin_base.rb, line 132
def json_read( path )
  file_data = file_read( path )
  if not file_data
    return false
  else
    begin
      return JSON.parse( file_data )
    rescue => e
      warn "An exception occurred while parsing JSON file: #{path}"
      warn e.message
      warn "  #{e.backtrace.join("\n  ")}"
      return false
    end
  end
end
method_missing( sym, *args, &block ) click to toggle source

When a method is missing, tries a call via pluginmanager. (Eliminates plugins.plugin_name.method_name calls -> plugin_name.method_name)

# File lib/rsence/plugins/plugin_base.rb, line 32
def method_missing( sym, *args, &block )
  @plugins.method_missing( sym, *args, &block )
end
open() click to toggle source

Extend to open objects like streams and database connections.

It is called by the {PluginManager#update_bundles! PluginManager} after the {#init} method, when everything is constructed after all plugins are loaded.

@return [nil]

# File lib/rsence/plugins/plugin_base.rb, line 53
def open
end
yaml_read( path ) click to toggle source

YAML reader utility

Reads the contents of the YAML file given in the path and returns as a parsed structure of the contents of the file.

@param [String] path The path is relative to the bundle path by default, unless it starts with ‘/’ or ‘..’; it’s simply processed by {#bundle_path} before reading the file.

@return [false] If the is no file, returns false @return [Object] Any valid structure defined by the YAML file, parsed to a Ruby object.

# File lib/rsence/plugins/plugin_base.rb, line 105
def yaml_read( path )
  file_data = file_read( path )
  if not file_data
    return false
  else
    begin
      return YAML.load( file_data )
    rescue Psych::SyntaxError => e
      warn "Syntax Error in YAML file: #{path} (#{e.message})"
      return false
    rescue => e
      warn "An exception occurred while parsing YAML file: #{path}"
      warn e.message
      warn "  #{e.backtrace.join("\n  ")}"
      return false
    end
  end
end
yaml_write( path, data ) click to toggle source

Yaml writer utility.

Wrapper for file_write Converts data to yaml and then calls file_write with the result.

# File lib/rsence/plugins/plugin_base.rb, line 173
def yaml_write( path, data )
  file_write( path, data.to_yaml )
end