Service Blueprints
Table of contents
A blueprint is an XML document that describes a Dream service. It must be registered with the Host service before it can be used to instantiate a new service.
The blueprint provides all the information that the Dream runtime requires to manage services. This information includes the type and assembly names of the service class, its human readable name, a copyright, a list of all features, and more.
Complete Blueprint
Following is a complete blueprint for the 8-ball service.
<blueprint>
<assembly Version="1.0.0.0" Culture="neutral" PublicKeyToken="null">dream.tutorial.8ball</assembly>
<class>MindTouch.Dream.Tutorial.EightBallService</class>
<name>Dream Tutorial 8-Ball</name>
<copyright>Copyright (c) 2006, 2007 MindTouch, Inc.</copyright>
<info>http://doc.opengarden.org/Dream_SDK/Tutorials/8-Ball</info>
<sid>http://services.mindtouch.com/dream/tutorial/2006/11/8ball</sid>
<configuration>
<entry>
<name>nolog</name>
<valuetype>void?</valuetype>
<description>When present, service will not create a log sub-service at /@log.</description>
</entry>
<entry>
<name>uri.host</name>
<valuetype>uri?</valuetype>
<description>Uri for host service (provided by Host).</description>
</entry>
<entry>
<name>uri.self</name>
<valuetype>uri</valuetype>
<description>Uri for current service (provided by Host).</description>
</entry>
</configuration>
<features>
<feature>
<pattern>DELETE:</pattern>
<description>Stop service</description>
<info>http://doc.opengarden.org/Dream_API/Generic_Features</info>
<method>DeleteService</method>
</feature>
<feature>
<pattern>GET:</pattern>
<description>Returns a random 8-ball message</description>
<info>http://doc.opengarden.org/Dream_SDK/Tutorials/8-Ball</info>
<method>GetAnswer</method>
</feature>
<feature>
<pattern>GET:@about</pattern>
<description>Retrieve service description</description>
<info>http://doc.opengarden.org/Dream_API/Generic_Features</info>
<method>GetServiceInfo</method>
</feature>
<feature>
<pattern>GET:@blueprint</pattern>
<description>Retrieve service blueprint</description>
<info>http://doc.opengarden.org/Dream_API/Generic_Features</info>
<method>GetServiceBlueprint</method>
</feature>
<feature>
<pattern>DELETE:@config</pattern>
<description>Deinitialize service</description>
<info>http://doc.opengarden.org/Dream_API/Generic_Features</info>
<method>DeleteConfig</method>
</feature>
<feature>
<pattern>GET:@config</pattern>
<description>Retrieve service configuration</description>
<info>http://doc.opengarden.org/Dream_API/Generic_Features</info>
<method>GetConfig</method>
</feature>
<feature>
<pattern>PUT:@config</pattern>
<description>Initialize service</description>
<info>http://doc.opengarden.org/Dream_API/Generic_Features</info>
<method>PutConfig</method>
</feature>
</features>
</blueprint>
Information Section
The first part of the blueprint describes general information about the service.
The <assembly> element tells what library to load before attempting to instantiate a service.
The <class> element specifies the class name. The class must be derived from IDreamService.
The <name> element provides the human readable name of the blueprint.
The <copyright> element assigns the copyright.
The <info> element points to online documentation about the service.
The <sid> element identifies the service type. A blueprint can have multiple <sid> elements corresponding to the different versions of the service.
Attribute: the DreamServiceAttribute is used to provide the information section of the blueprint.
<assembly Version="1.0.0.0" Culture="neutral" PublicKeyToken="null">dream.tutorial.8ball</assembly> <class>MindTouch.Dream.Tutorial.EightBallService</class> <name>Dream Tutorial 8-Ball</name> <copyright>Copyright (c) 2006, 2007 MindTouch, Inc.</copyright> <info>http://doc.opengarden.org/Dream_SDK/Tutorials/8-Ball</info> <sid>http://services.mindtouch.com/dream/tutorial/2006/11/8ball</sid>
Configuration Section
The second part of the blueprint provides information on how to initialize a service. Each entry corresponds to a config parameter (element or attribute) used to initialize a service.
The <key> element contains the name to the configuration item.
The <valuetype> element describe the value type of the item.
The <description> element provides a human readable description of the config parameter.
Attribute: the DreamServiceConfig attribute is used to describe each config parameter.
<configuration>
<entry>
<name>path</name>
<valuetype>uri</valuetype>
<description>Uri for current service (provided by Host).</description>
</entry>
</configuration>
Features Section
The third section of the blueprint describes the features of the service.
The <pattern> element describes the HTTP verb and URI pattern matched by the feature.
The <description> element provides a human readable description of the feature.
The <info> element points to online documentation about the feature.
The <method> element name the instance method to invoke in the instance.
The param <name> element describes the name of a query parameter.
The param <valuetype> element describes the value type of the query parameter.
The param <description> element a human readable description of the query parameter.
Attribute: the DreamFeature and DreamFeatureParam attributes are used to describe each feature.
<features>
<feature>
<pattern>DELETE:</pattern>
<description>Stop service</description>
<info>http://doc.opengarden.org/Dream_API/Generic_Features</info>
<method>DeleteService</method>
<param>
<name>name</name>
<valuetype>string</valuetype>
<description>Name of assembly to load</description>
</param>
</feature>
</features>
Partial Blueprint
It is also possible to provide a partial blueprint when using Dream attributes to define services. The following is the partial blueprint for the same Statistics service.
<blueprint> <asseembly>dream.tutorial.8ball</assembly> <type>MindTouch.Dream.Tutorial.EightBallService</type> </blueprint>
The remaining information is extracted dynamically from the Dream attributes on the service class when the service is registered. This should make for a pretty compelling case to use Dream attributes!
Registration
A blueprint is registered by posting it to http://localhost:8081/host/register (assuming your Dream server runs on port 8081). After that, it can be used to instantiate service by using http://localhost:8081/host/start.
To retrieve a list of all registered blueprints, use your browse to go to http://localhost:8081/host/bluebrints.
To see a specific blueprint, use your browser to go to http://localhost:8081/host/blueprints/TYPENAME.
- Tag page
-
- What links here
