class RDF::Sesame::Connection

A connection to a Sesame 2.0-compatible HTTP server.

Instances of this class represent HTTP connections to a Sesame server, abstracting away the protocol and transport-level details of how the connection is actually established and how requests and responses are implemented and performed.

Currently, connections are internally implemented using [`Net::HTTP`](ruby-doc.org/core/classes/Net/HTTP.html) from Ruby's standard library, and connections are always transient, i.e. they do not persist from one request to the next and must always be reopened when used. A future improvement would be to support persistent `Keep-Alive` connections.

Connections are at any one time in one of the two states of {#close closed} or {#open open} (see {#open?}). You do not generally need to call {#close} explicitly.

@example Opening a connection to a Sesame server (1)

url  = URI.parse("http://localhost:8080/openrdf-sesame")
conn = RDF::Sesame::Connection.open(url)
...
conn.close

@example Opening a connection to a Sesame server (2)

url = URI.parse("http://localhost:8080/openrdf-sesame")
RDF::Sesame::Connection.open(url) do |conn|
  ...
end

@example Performing an HTTP GET on a Sesame server

RDF::Sesame::Connection.open(url) do |conn|
  conn.get("/openrdf-sesame/protocol") do |response|
    version = response.body.to_i
  end
end

@see ruby-doc.org/core/classes/Net/HTTP.html

Attributes

connected[R]

@return [Boolean]

connected?[R]

@return [Boolean]

headers[R]

@return [Hash{String => String}]

open?[R]

@return [Boolean]

options[R]

@return [Hash{Symbol => Object}]

pass[R]

@return [String]

proxy_host[R]

@return [String]

proxy_port[R]

@return [Number]

user[R]

@return [String]

Public Class Methods

new(url = nil, options = {}) { |self| ... } click to toggle source

Initializes this connection.

@param [RDF::URI, to_s] url @param [Hash{Symbol => Object}] options @yield [connection] @yieldparam [Connection]

# File lib/rdf/sesame/connection.rb, line 95
def initialize(url = nil, options = {}, &block)
  url ||= "http://localhost:8080/openrdf-sesame"
  parsed = URI.parse(url.to_s)

  @user = options.delete(:user) || parsed.user || nil
  @pass = options.delete(:pass) || parsed.password || nil

  # Preserve only those URI components that we actually require for
  # establishing a connection to the HTTP server in question:
  parsed.user = parsed.password = nil
  @url = parsed

  @proxy_host = options.delete(:proxy_host) || nil
  @proxy_port = options.delete(:proxy_port) || nil
  @headers   = options.delete(:headers) || {}
  @options   = options
  @connected = false

  if block_given?
    case block.arity
      when 1 then yield self
      else instance_eval(&block)
    end
  end
end
open(url, options = {}) { |conn| ... } click to toggle source

Opens a connection to a Sesame server.

@param [RDF::URI, to_s] url @param [Hash{Symbol => Object}] options @yield [connection] @yieldparam [Connection] @return [Connection]

# File lib/rdf/sesame/connection.rb, line 75
def self.open(url, options = {}, &block)
  self.new(url, options) do |conn|
    if conn.open(options) && block_given?
      case block.arity
        when 1 then yield conn
        else conn.instance_eval(&block)
      end
    else
      conn
    end
  end
end

Public Instance Methods

close() click to toggle source

Closes the connection to the Sesame server.

You do not generally need to call {#close} explicitly.

@return [void]

# File lib/rdf/sesame/connection.rb, line 261
def close
  if connected?
    # TODO: support persistent connections
    @connected = false
  end
end
Also aliased as: close!
close!()
Alias for: close
delete(path, headers = {}) { |response| ... } click to toggle source

Performs an HTTP DELETE request for the given Sesame `path`.

@param [String, to_s] path @param [Hash{String => String}] headers @yield [response] @yieldparam [Net::HTTPResponse] response @return [Net::HTTPResponse]

# File lib/rdf/sesame/connection.rb, line 344
def delete(path, headers = {})
  Net::HTTP::Proxy(@proxy_host, @proxy_port).start(host, port, :use_ssl => self.secure?) do |http|
    request = Net::HTTP::Delete.new(url(path.to_s), @headers.merge(headers))
    request.basic_auth @user, @pass unless @user.nil? || @pass.nil?
    response = http.request(request)
    if block_given?
      yield response
    else
      response
    end
  end
end
get(path, headers = {}) { |response| ... } click to toggle source

Performs an HTTP GET request for the given Sesame `path`.

@param [String, to_s] path @param [Hash{String => String}] headers @yield [response] @yieldparam [Net::HTTPResponse] response @return [Net::HTTPResponse]

# File lib/rdf/sesame/connection.rb, line 278
def get(path, headers = {})
  Net::HTTP::Proxy(@proxy_host, @proxy_port).start(host, port, :use_ssl => self.secure?) do |http|
    request = Net::HTTP::Get.new(url(path.to_s), @headers.merge(headers))
    request.basic_auth @user, @pass unless @user.nil? || @pass.nil?
    response = http.request(request)
    if block_given?
      yield response
    else
      response
    end
  end
end
host() click to toggle source

Returns the host name for this connection.

@return [String]

# File lib/rdf/sesame/connection.rb, line 183
def host
  @url.host.to_s
end
Also aliased as: hostname
hostname()
Alias for: host
insecure?() click to toggle source

Returns `true` unless this is an HTTPS connection.

@return [Boolean]

# File lib/rdf/sesame/connection.rb, line 125
def insecure?
  !secure?
end
inspect() click to toggle source

Returns a developer-friendly representation of this connection.

@return [String]

# File lib/rdf/sesame/connection.rb, line 226
def inspect
  sprintf("#<%s:%#0x(%s)>", self.class.name, object_id, to_s)
end
open(options = {}) { |self| ... } click to toggle source

Establishes the connection to the Sesame server.

@param [Hash{Symbol => Object}] options @yield [connection] @yieldparam [Connection] connection @raise [TimeoutError] if the connection could not be opened @return [Connection]

# File lib/rdf/sesame/connection.rb, line 238
def open(options = {})
  unless connected?
    # TODO: support persistent connections
    @connected = true
  end

  if block_given?
    result = yield self
    close
    result
  else
    self
  end
end
Also aliased as: open!
open!(options = {})
Alias for: open
password?() click to toggle source

Returns `true` if there is password information for this connection.

@return [Boolean]

# File lib/rdf/sesame/connection.rb, line 175
def password?
  !password.nil?
end
port() click to toggle source

Returns the port number for this connection.

@return [Integer]

# File lib/rdf/sesame/connection.rb, line 202
def port
  @url.port
end
port?() click to toggle source

Returns `true` if the port number for this connection differs from the standard HTTP or HTTPS port number (80 and 443, respectively).

@return [Boolean]

# File lib/rdf/sesame/connection.rb, line 194
def port?
  !@url.port.nil? && @url.port != (insecure? ? 80 : 443)
end
post(path, data, headers = {}) { |response| ... } click to toggle source

Performs an HTTP POST request for the given Sesame `path`.

@param [String, to_s] path @param [String, to_s] data @param [Hash{String => String}] headers @yield [response] @yieldparam [Net::HTTPResponse] response @return [Net::HTTPResponse]

# File lib/rdf/sesame/connection.rb, line 300
def post(path, data, headers = {})
 Net::HTTP::Proxy(@proxy_host, @proxy_port).start(host, port, :use_ssl => self.secure?) do |http|
    request = Net::HTTP::Post.new(url(path.to_s), @headers.merge(headers))
    request.body = data.to_s
    request.basic_auth @user, @pass unless @user.nil? || @pass.nil?
    response = http.request(request)
    if block_given?
      yield response
    else
      response
    end
  end
end
put(path, data, headers = {}) { |response| ... } click to toggle source

Performs an HTTP PUT request for the given Sesame `path`.

@param [String, to_s] path @param [Hash{String => String}] headers @yield [response] @yieldparam [Net::HTTPResponse] response @return [Net::HTTPResponse]

# File lib/rdf/sesame/connection.rb, line 322
def put(path, data, headers = {})
  Net::HTTP::Proxy(@proxy_host, @proxy_port).start(host, port, :use_ssl => self.secure?) do |http|
    request = Net::HTTP::Put.new(url(path.to_s), @headers.merge(headers))
    request.body = data.to_s
    request.basic_auth @user, @pass unless @user.nil? || @pass.nil?
    response = http.request(request)
    if block_given?
      yield response
    else
      response
    end
  end
end
scheme() click to toggle source

Returns `:http` or `:https` to indicate whether this is an HTTP or HTTPS connection, respectively.

@return [Symbol]

# File lib/rdf/sesame/connection.rb, line 142
def scheme
  @url.scheme.to_s.to_sym
end
secure?() click to toggle source

Returns `true` if this is an HTTPS connection.

@return [Boolean]

# File lib/rdf/sesame/connection.rb, line 133
def secure?
  scheme == :https
end
to_s() click to toggle source

Returns a string representation of this connection.

@return [String]

# File lib/rdf/sesame/connection.rb, line 218
def to_s
  @url.to_s
end
to_uri() click to toggle source

Returns the URI representation of this connection.

@return [RDF::URI]

# File lib/rdf/sesame/connection.rb, line 210
def to_uri
  @url
end
url(path) click to toggle source
# File lib/rdf/sesame/connection.rb, line 357
def url(path)
  if path
    File.join(@url.to_s, path.to_s)
  else
    @url.to_s
  end
end
user?() click to toggle source

Returns `true` if there is user name information for this connection.

@return [Boolean]

# File lib/rdf/sesame/connection.rb, line 167
def user?
  !user.nil?
end
userinfo() click to toggle source

Returns any user name and password information for this connection.

@return [String] “username:password”

# File lib/rdf/sesame/connection.rb, line 159
def userinfo
  @url.userinfo
end
userinfo?() click to toggle source

Returns `true` if there is user name and password information for this connection.

@return [Boolean]

# File lib/rdf/sesame/connection.rb, line 151
def userinfo?
  !@url.userinfo.nil?
end