+++ /dev/null
----
-layout: default
-title: Data Definition Language
----
-[WritingAgents]: /mcollective/reference/basic/basic_agent_and_client.html
-[SimpleRPCClients]: /mcollective/simplerpc/clients.html
-[ResultsandExceptions]: /mcollective/simplerpc/clients.html#results_and_exceptions
-[SimpleRPCAuditing]: /mcollective/simplerpc/auditing.html
-[SimpleRPCAuthorization]: /mcollective/simplerpc/authorization.html
-[WritingAgentsScreenCast]: http://mcollective.blip.tv/file/3808928/
-[DDLScreenCast]: http://mcollective.blip.tv/file/3799653
-[RPCUtil]: /mcollective/reference/plugins/rpcutil.html
-[ValidatorPlugins]: /mcollective/reference/plugins/validator.html
-
-As with other remote procedure invocation systems MCollective has a DDL that defines what remote methods are available, what inputs they take and what outputs they generate.
-
-In addition to the usual procedure definitions we also keep meta data about author, versions, license and other key data points.
-
-The DDL is used in various scenarios:
-
- * The user can access it in the form of a human readable help page
- * User interfaces can access it in a way that facilitate auto generation of user interfaces
- * The RPC client auto configures and use appropriate timeouts in waiting for responses
- * Before sending a call over the network inputs get validated so we do not send unexpected data to remote nodes.
- * Module repositories can use the meta data to display a standard view of available modules to assist a user in picking the right ones.
- * The server will validate incoming requests prior to sending it to agents
-
-We've created [a screencast showing the capabilities of the DDL][DDLScreenCast] that might help give you a better overview.
-
-**NOTE:** As of version 2.1.1 the DDL is required on all servers before an agent will be activated
-
-## Examples
-We'll start with a few examples as I think it's pretty simple what they do, and later on show what other permutations are allowed for defining inputs and outputs.
-
-A helper agent called [_rpcutil_][RPCUtil] is included that helps you gather stats, inventory etc about the running daemon. This helper has a full DDL included, see the plugins dir for this agent.
-
-The typical service agent is a good example, it has various actions that all more or less take the same input. All but status would have almost identical language.
-
-### Meta Data
-First we need to define the meta data for the agent itself:
-
-{% highlight ruby linenos %}
-metadata :name => "SimpleRPC Service Agent",
- :description => "Agent to manage services using the Puppet service provider",
- :author => "R.I.Pienaar",
- :license => "GPLv2",
- :version => "1.1",
- :url => "http://projects.puppetlabs.com/projects/mcollective-plugins/wiki",
- :timeout => 60
-{% endhighlight %}
-
-It's fairly obvious what these all do, *:timeout* is how long the MCollective daemon will let the threads run.
-
-## Required versions
-As of MCollective 2.1.2 you can indicate which is the lowest version of MCollective needed to use a plugin. Plugins that do not meet the requirement can not be used.
-
-{% highlight ruby linenos %}
-requires :mcollective => "2.0.0"
-{% endhighlight %}
-
-You should add this right after the metadata section in the DDL
-
-## Actions, Input and Output
-Defining inputs and outputs is the hardest part, below first the *status* action:
-
-{% highlight ruby linenos %}
-action "status", :description => "Gets the status of a service" do
- display :always # supported in 0.4.7 and newer only
-
- input :service,
- :prompt => "Service Name",
- :description => "The service to get the status for",
- :type => :string,
- :validation => '^[a-zA-Z\-_\d]+$',
- :optional => false,
- :default => "mcollective",
- :maxlength => 30
-
- output :status,
- :description => "The status of service",
- :display_as => "Service Status",
- :default => "unknown status"
-end
-{% endhighlight %}
-
-As you see we can define all the major components of input and output parameters. *:type* can be one of various values and each will have different parameters, more on that later.
-
-As of version 2.1.1 the outputs can define a default value. For agents the reply structures are pre-populated with all the defined outputs, if no default is supplied a default of nil will be set.
-
-As of version 2.3.1 the inputs can also define default values, this is only processed and applied for non optional inputs.
-
-By default mcollective only show data from actions that failed, the *display* line above tells it to always show the results. Possible values are *:ok*, *:failed* (the default behavior) and *:always*.
-
-Finally the service agent has 3 almost identical actions - *start*, *stop* and *restart* - below we use a simple loop to define them all in one go.
-
-{% highlight ruby linenos %}
-["start", "stop", "restart"].each do |act|
- action act, :description => "#{act.capitalize} a service" do
- input :service,
- :prompt => "Service Name",
- :description => "The service to #{act}",
- :type => :string,
- :validation => '^[a-zA-Z\-_\d]+$',
- :optional => false,
- :maxlength => 30
-
- output :status,
- :description => "The status of service after #{act}",
- :display_as => "Service Status",
- :default => "unknown status"
- end
-end
-{% endhighlight %}
-
-All of this code just goes into a file, no special class or module bits needed, just save it as *service.ddl* in the same location as the *service.rb*.
-
-Importantly you do not need to have the *service.rb* on a machine to use the DDL, this means on machines that are just used for running client programs you can just drop the *.ddl* files into the agents directory.
-
-You can view a human readable version of this using *mco plugin doc <agent>* command:
-
-{% highlight console %}
-% mco plugin doc service
-SimpleRPC Service Agent
-=======================
-
-Agent to manage services using the Puppet service provider
-
- Author: R.I.Pienaar
- Version: 1.1
- License: GPLv2
- Timeout: 60
- Home Page: http://projects.puppetlabs.com/projects/mcollective-plugins/wiki
-
-
-
-ACTIONS:
-========
- restart, start, status, stop
-
- restart action:
- ---------------
- Restart a service
-
- INPUT:
- service:
- Description: The service to restart
- Prompt: Service Name
- Type: string
- Validation: ^[a-zA-Z\-_\d]+$
- Length: 30
-
-
- OUTPUT:
- status:
- Description: The status of service after restart
- Display As: Service Status
-{% endhighlight %}
-
-### Optional Inputs
-The input block has a mandatory *:optional* field, when true it would be ok if a client attempts to call the agent without this input supplied. If it is supplied though it will be validated.
-
-### Types of Input
-As you see above the input block has *:type* option, types can be *:string*, *:list*, *:boolean*, *:integer*, *:float* or *:number*
-
-#### :string type
-The string type validates initially that the input is infact a String, then it validates the length of the input and finally matches the supplied Regular Expression.
-
-Both *:validation* and *:maxlength* are required arguments for the string type of input.
-
-If you want to allow unlimited length text you can make *:maxlength => 0* but use this with care.
-
-As of version 2.2.0 a new plugin type called [Validator Plugins][ValidatorPlugins] exist that allow you to supply your own validations for *:string* types.
-
-#### :list type
-List types provide a list of valid options and only those will be allowed, see an example below:
-
-{% highlight ruby linenos %}
-input :action,
- :prompt => "Service Action",
- :description => "The action to perform",
- :type => :list,
- :optional => false,
- :list => ["stop", "start", "restart"]
-{% endhighlight %}
-
-In user interfaces this might be displayed as a drop down list selector or another kind of menu.
-
-#### :boolean type
-
-The value input should be either _true_ or _false_ actual boolean values. This feature was introduced in version _0.4.9_.
-
-#### :integer type
-
-The value input should be an integer number like _1_ or _100_ but not _1.1_. This feature was introduced in version _1.3.2_
-
-#### :float type
-
-The value input should be a floating point number like _1.0_ but not _1_. This feature was introduced in version _1.3.2_
-
-#### :number type
-
-The value input should be an integer or a floating point number. This feature was introduced in version _1.3.2_
-
-#### :any type
-
-The value input can be any type, this allows you to send rich objects like arrays of hashes around, it effectively disables validation of the type of input.
-
-The :any type is deprecated and will be removed after version 2.2.x.
-
-### Accessing the DDL
-While programming client applications or web apps you can gain access to the DDL for any agent in several ways:
-
-{% highlight ruby linenos %}
-require 'mcollective'
-
-config = MCollective::Config.instance
-config.loadconfig(options[:config])
-
-ddl = MCollective::DDL.new("service")
-puts ddl.help("#{config.configdir}/rpc-help.erb")
-{% endhighlight %}
-
-This will produce the text help output from the above example, you can supply any ERB template to format the output however you want.
-
-You can also access the data structures directly:
-
-{% highlight ruby linenos %}
-ddl = MCollective::DDL.new("service")
-puts "Meta Data:"
-pp ddl.meta
-
-puts
-puts "Status Action:"
-pp ddl.action_interface("status")
-{% endhighlight %}
-
-{% highlight ruby linenos %}
-Meta Data:
-{:license=>"GPLv2",
- :author=>"R.I.Pienaar",
- :name=>"SimpleRPC Service Agent",
- :timeout=>60,
- :version=>"1.1",
- :url=>"http://projects.puppetlabs.com/projects/mcollective-plugins/wiki",
- :description=>"Agent to manage services using the Puppet service provider"}
-
-Status Action:
-{:action=>"status",
- :input=>
- {:service=>
- {:validation=>"^[a-zA-Z\\-_\\d]+$",
- :maxlength=>30,
- :prompt=>"Service Name",
- :type=>:string,
- :optional=>false,
- :description=>"The service to get the status for"}},
- :output=>
- {"status"=>
- {:display_as=>"Service Status", :description=>"The status of service"}},
- :description=>"Gets the status of a service"}
-
-{% endhighlight %}
-
-The ddl object is also available on any *rpcclient*:
-
-{% highlight ruby linenos %}
-service = rpcclient("service")
-pp service.ddl.meta
-{% endhighlight %}
-
-In the case of accessing it through the service as in this example, if there was no DDL file on the machine for the service agent you'd get a *nil* back from the ddl accessor.
-
-### Input Validation
-As mentioned earlier the client does automatic input validation using the DDL, if validation fails you will get an *MCollective::DDLValidationError* exception thrown with an appropriate message.
Code Review / packages / precise / mcollective.git / blobdiff