Simple example

deep.protocols.myProtoc = { 
	get:function(request, options){ 
		return "deepjs, made with "+request; 
	}
};
//...
deep.get("myProtoc::love").log();

As you could see, deep.protocols (formally a singleton registry) is the main namespace where you store your provider. You could use deep.get("myProviderName::my_request") to call it.

By default, all that your provider needs to implement is the "get" method (see below for other methods).

deep.get(req, opt)

deep.get("dummy::hello world").log();

(See natives protocols for information on 'dummy' provider.)

This method simply parses the provided request, retrieves the provider gived by the protocol, prepares it if necessary, and use it to get request response.

Returns a Promise that hold the loaded ressource. Or an error if something was wrong.

If request isn't a String, or if request doesn't contain a protocol, it is injected without load (as this) in promise.

deep.get({a:true}).log();
deep.get("hello world").log();

deep.getAll([req1, req2, ...], opt)

deep
.getAll(["dummy::hello world", "eval::true", 12, { b:"hello" }])
.log();

(See natives protocols for information on 'dummy' and 'eval' providers.)

Same thing than before, this method simply parses provided requests, retrieves associated providers, prepares them if necessary, and use them to get requests responses.

Returns a Promise that will return an array containing the loaded ressources. Or an error if something was wrong.

If any request isn't a String, or if "string requests" don't contain a protocol, they are returned 'as this'.

sub-protocol

If your provider implements others methods than 'get' (and 'range' : see below), you could access them by using "sub-protocol" notation : e.g. "myProtoc.myMethod::my_request"

deep.protocols.myProtoc = {
	//...
	myMethod:function(request, options){
		return "Response from myProtoc.myMethod : Hello "+request;
	}
}
//...
deep.get("myProtoc.myMethod::foo")
.log();

range

If your provider implements a 'range' method (as below - and as restful stores do by default), you could access it with this particular protocol notation :

deep.protocols.myProtoc = {
	range:function(start, end, request, options){
		// as 'range' method (from restful stores) normally returns a _deep_range_ object 
		// that contains all informations on requested range : we mimic it here.
		// (it contains normally more fields than here)
		return { _deep_range_:true, start:start, end:end, query:request /*, ....*/ };
	}
}
deep.get("myProtoc(0,23)::foo")
.log();

See range manipulation in collection store for full infos.

deep.protocol(name)

Simple function that will retrieve protocol by name. It's this method that deepjs use to get a particular protocol when requests are parsed. So that's trully the service locator.

deep.protocols.myProtoc = {
	get:function(request, options){
		return "hello world : "+request;
	}
}
var provider = deep.protocol("myProtoc");
deep.log(provider);

But it does more than just seeking in deep.protocols. It will manage protocols contextualization for you.

What does it mean ? it means that protocols implementation could be totally different depending on user roles, plateform, production flags, etc.

And deep.protocol(name) will provide you the good one automagically. Firstly if providers are OCManager, and secondly through deep.context.protocols...

It will prepare it for you (see below)

OCM and protocols

When you place an OCManager in protocols namespaces (deep.protocols or deep.context.protocols - see below), deep.protocol will return the response of the OCManager (depending on current modes - from deep.context or not) in place of the OCManager itself.

deep.protocols.myProtoc = deep.ocm({
	mode1:{
		get:function(request, options){
			return "Response from mode1 : hello "+request;
		}
	},
	mode2:{
		get:function(request, options){
			return "Response from mode2 : bye "+request;
		}
	}
},  { sensibleTo:"modeGroup" });
//...
deep.Modes("modeGroup", "mode1");
//...
deep.get("myProtoc::John").log();
//...
deep.Modes("modeGroup", "mode2");
//...
deep.get("myProtoc::John").log();

deep.context and protocols

Warning You should read context docs before trying to understand this.

We've said until here, that there is only one namespace where store providers. That's not totally true...

When you wan't to have a provider only accessible in a certain (deep.)context, you could use the deep.context.protocols namespace to store it.

deep.protocol('xxx') will check first if 'xxx' is present in deep.context.protocols, before checking in deep.protocols and preparing provider.

deep.protocols.myProtoc = {
	get:function(req){
		return "hello "+req+" from general protocols";
	}
};

deep.get("myProtoc::john")
.log()
.contextualise()		// shallow copy current deep.context locally (see deep.context docs)
.done(function(){
	deep.context.protocols = deep.context.protocols || {};
	deep.context.protocols.myProtoc = {
		get:function(req){
			return "hello "+req + " from contextualised protocols";
		}
	};
})
.delay(100)	// async simulation
.done(function(){
	return deep.get("myProtoc::john");
})
.log();

deep.delay(50) // async simulation
.done(function(){
	return deep.get("myProtoc::john");
})
.log();

Protocol preparation

While deep.protocol(name) gets your provider, it flattens it (deep.flatten - if it's an ocm by example) and initialise it if needed (if you've provided an init method in your provider).

Remarque So deep.protocol(xxx) could return a Promise that you'll need to wait for if you use it directly. This promise will return prepared provider.

deep.protocols.myProtoc = deep.ocm({
	mode1:{
		myVar:"lolipop",
		init:function(){
			deep.log("myProtoc init");
		},
		get:function(req){
			return "("+this.myVar+") and you say : "+req;
		}
	},
	mode2:{
		_backgrounds:["this::../mode1"],
		myVar:"hollywood"
	}
}, { sensibleTo:"myGroup"});
//...
deep.Modes("myGroup", "mode2");
//...
deep.get("myProtoc::powaaaa").log();

Resumed

Ressource path format

If your provider implements a get method : you could use it through "myProvider::myRequest".

If your provider implements a range method : you could use it through "myProvider(0,23)::myRequest".

If your provider implements others method : you could use it through "myProvider.myMethod::myRequest".


Protocol retrieval

It will seek first in deep.context.protocols, then, if nothing was found there, it will look in deep.protocols.

If something was found, before return, it will look if it's an OCManager. If so, it will get the result from OCManager with default modes. If there is an init method in the provider (after ocm check), it will fire it and wait initialisation end before returning prepared provider.