Previous topic

Service interface

Next topic

UserDeployment interface

This Page

Publication interface

The publication class is in fact an interface. It represents, in those case that a service needs the preparation, the logic for that preparation.

So the publication class is responsible of doing whatever is needed to get the deployed service (that is the compound of a service, an os manager, transports and authenticators) ready for deploying user consumables.

Note that not all services needs to implement this class, only in those case where that service declares that a publication is needed.

As functional sample of a publication, imagine that we want to assing KVM COW machines to users. The publication class can make a clone of the base machine (that the service itself has taken note of which one is), and then the COWs will be created from this cloned machine.

For a detailed example of a service provider, you can see the provided publication sample

class uds.core.services.Publication(environment, **kwargs)

This class is in fact an interface, and defines the logic of a publication for a Service.

A publication is the preparation of the needs of a service before it can be provided to users. One good sample of this is, in case of virtual machines, to copy a machine to provide COWS of this copy to users.

As always, do not forget to invoke base class __init__ if you override it as this:

super(self.__class__, self).__init__(environment, **kwargs)

This is a MUST, so internal structured gets filled correctly, so don’t forget it!.

The preferred method is not to override init, but provide the initialize(), that will be invoked just after all internal initialization is completed.

Normally objects of classes deriving from this one, will be serialized, called, deserialized. This means that all that you want to ensure that is keeped inside the class must be serialized and unserialized, because there is no warantee that the object will get two methods invoked without haven’t been remoded from memory and loaded again, this means, IMPLEMENT marshal and unmarshal with all attributes that you want to keep.

cancel()

This is a task method. As that, the expected return values are State values RUNNING, FINISHED or ERROR.

This method is invoked whenever the core needs a cancelation of current operation. This will happen if we are, for example, preparing the service for users, but the administration request to stop doing this.

This method MUST be provided, even if you do nothing here (in that case, simply return State.FINISHED). Default implementation will raise an exception if it gets called

Note:All task methods, like this one, are expected to handle all exceptions, and never raise an exception from these methods to the core. Take that into account and handle exceptions inside this method.
checkState()

This is a task method. As that, the expected return values are State values RUNNING, FINISHED or ERROR.

This method will be invoked whenever a publication is started, but it do not finish in 1 step.

The idea behind this is simple, we can initiate an operation of publishing, that will be done at :py:meth:.publish method.

If this method returns that the operation has been initiated, but not finished (State.RUNNING), the core will keep calling this method until checkState returns State.FINISHED (or State.error).

You MUST always provide this method if you expect the publication no to be done in 1 step (meaning this that if publish can return State.RUNNING, this will get called)

Note:All task methods, like this one, are expected to handle all exceptions, and never raise an exception from these methods to the core. Take that into account and handle exceptions inside this method.
destroy()

This is a task method. As that, the expected return values are State values RUNNING, FINISHED or ERROR.

Invoked for destroying a deployed service Do whatever needed here, as deleting associated data if needed (i.e. a copy of the machine, snapshots, etc...)

This method MUST be provided, even if you do nothing here (in that case, simply return State.FINISHED). Default implementation will raise an exception if it gets called

Note:All task methods, like this one, are expected to handle all exceptions, and never raise an exception from these methods to the core. Take that into account and handle exceptions inside this method.
dsName()

Utility method to access the declared deployed service name.

This name is set by core, using the administrator provided data at administration interface.

finish()

Invoked when Publication manager noticed that the publication has finished. This give us the opportunity of cleaning up things (as stored vars, etc..) Returned value, if any, is ignored

Default implementation does nothing. You can leave default method if you are going to do nothing.

initialize()

This method will be invoked from __init__ constructor. This is provided so you don’t have to provide your own __init__ method, and invoke base class __init__. This will get invoked when all initialization stuff is done, so you can here access service, osManager, ...

osManager()

Utility method to access os manager for this publication.

Returns

Parent service instance object (not database object) The returned value can be None if no Os manager is needed by the service owner of this publication.
publish()

This method is invoked whenever the administrator requests a new publication.

The method is not invoked directly (i mean, that the administration request do no makes a call to this method), but a DelayedTask is saved witch will initiate all publication stuff (and, of course, call this method).

You MUST implement it, so the publication do really something. All publications can be synchronous or asynchronous.

The main difference between both is that first do whatever needed, (the action must be fast enough to do not block core), returning State.FINISHED.

The second (asynchronous) are publications that could block the core, so it have to be done in more than one step.

An example publication could be a copy of a virtual machine, where:
  • First we invoke the copy operation to virtualization provider
  • Second, we kept needed values inside instance so we can serialize them whenever requested
  • Returns an State.RUNNING, indicating the core that the publication has started but has to finish sometime later. (We do no check again the state and keep waiting here, because we will block the core untill this operation is finished).
Note:This method MUST be provided, an exception is raised if not.
Note:All task methods, like this one, are expected to handle all exceptions, and never raise an exception from these methods to the core. Take that into account and handle exceptions inside this method.
reasonOfError()

If a publication produces an error, here we must return the reason why it happened. This will be called just after publish or checkPublishingState if they return State.ERROR

The returned value, an string, will be used always by administration interface, meaning this that the translation environment will be ready, and that you can use ugettext to return a version that can be translated to administration interface language.

revision()

Utility method to access the revision of this publication This is a numeric value, and is set by core

service()

Utility method to access parent service of this publication

Returns

Parent service instance object (not database object)