Overview

ifmap.js is an IF-MAP client library implementation in JavaScript. It should run in any reasonably modern web browser or other JavaScript interpreter. For a description of IF-MAP see the specification and other documentation at ifmapdev.com/documentation. Due to the same-origin policy within the browser, IF-MAP clients built with ifmap.js must send all requests through a proxy, sold separately. For a fully-functioning example see jsmap.

Enough talk. Here's an...

Example

// Create a client and establish a session with a MAP server
var client = new IfmapClient('https://itsa:[email protected]:8686/ifmap');
client.newSession();

console.log(client.request); // Check out the IF-MAP request we just sent

// Create some identifiers
var me = new IfmapIdentifier('identity', {'type': 'username', 'name': 'amb'});
var mySession = new IfmapIdentifier('access-request', {'name': '103:aw8h13nadwnpefgasd'});

// And some metadata
var authenticatedAs = new IfmapMetadata('authenticated-as');

// And publish it
client.publishUpdate([me, mySession], authenticatedAs, function(data, status, xhr) { console.log(data['soap']) });

Dependencies

ifmap.js relies on jQuery. Specifically, jQuery.post() and jQuery.each() are used heavily.

Known Issues

• Pulling out session-id and publisher-id elements from a newSession response won't work unless the elements are namespaced with the 'ifmap' prefix.
• IfmapMetadata needs work to support all standard IF-MAP metadata types.
• Support for custom metadata isn't included.
• Support for subscriptions is nonexistent. Maybe soon...

IfmapClient

The IfmapClient constructor takes two arguments, proxyURI and mapURI. The constructor sets up an IF-MAP client and points it at mapURI, presumably the SOAP endpoint of some MAP server. The client works through a proxy, sold separately. The proxy needs to listen at proxyURI for POST requests with parameters 'url' and 'soap', which it should use to send a SOAP request to 'url' with 'soap' as the body.

IfmapClient(proxyURI, mapURI)

• proxyURI: A uri for this client's proxy, as a string.
• mapURI: A uri for the MAP server that this client should talk to, as a string.

Each IF-MAP request (except attach-session and subscribe) has a corresponding function on IfmapClient. For all the following functions, the callback argument is passed directly to jQuery.post() as the success argument. See the jQuery.post() documentation for more.

• IfmapClient.newSession(callback)

  Establish a new session with the MAP server.

• IfmapClient.publishUpdate(identifiers, metadata, callback)

  • identifiers: an array of one or two IfmapIdentifier objects.
  • metadata: an IfmapMetadata object.

  Publish metadata on an identifier or a link.

• IfmapClient.publishDelete(identifiers, filter, callback)

  • identifiers: an array of one or two IfmapIdentifier objects.
  • filter: a filter string (see the IF-MAP spec for formatting details).

  Delete metadata from an identifier or a link.

• IfmapClient.search(identifier, params, callback)

  • identifier: an IfmapIdentifier object.
  • params: an object containing name/value pairs for IF-MAP search params such as match-links and max-depth.

  Search for metadata starting at an identifier.

• IfmapClient.purgePublisher(callback)

  Purge all metadata published by this client.

IfmapIdentifier, IfmapMetadata

An IfmapIdentifier object is pretty simple. Once constructed, it's not really meant to be changed. The constructor takes two arguments, type and params.

IfmapIdentifier(type, params)

• type: An IF-MAP identifier type, as a string (e.g. 'ip-address').
• params: An object containing attribute/value pairs for this identifier (e.g. {'type': 'IPv4', 'value': '172.16.1.250'}).

An IfmapMetadata object is even simpler (for now). It's constructor only takes a type argument (since only simple metadata types are supported).

IfmapMetadata(type)

• type: A simple IF-MAP metadata type, as a string (e.g. 'access-request-ip').

Both kinds of objects provide one useful function, toXML(), which serializes the object as a string of XML and returns it.