View source for Virtual Platform

== Role ==

The ''Virtual Platform'' is a model to be extended for transparently interfacing a potentially unlimited number of hosting environments. This library provides an implementation of the ''Virtual Platform'' model. By extending and implementing the classes and interfaces of the library it is possible to bridge and manage the lifecycle of execution units running on a different platform than gCore. 

The gCube enabling technology is capable of dynamically instantiating platforms (along with their resources) compliant to such a model. When new software designed to run on a specific platform is uploaded in the [[Software Repository]] and then requested for deployment, a virtual image of the target platform is created to manage such software.

== Design ==
The library has been designed having in mind its two-fold role:

* to model the basic behavior of a virtual platform (package ''org.gcube.vremanagement.virtualplatform.model'')
* to offer a platform-independent way to instantiate and interact with a concrete virtual platform implementation (package ''org.gcube.vremanagement.virtualplatform.image'')


== Implementing a new virtual platform ==

The complexity of the implementation of a virtual platform depends on the interface of the concrete platform to interface. However, creating a bridge with the gCube enabling layer requires an handful steps described below.

=== Defining the platform interface ===

=== Configuration ===

A platform configuration consists of a properties file with the following syntax:

<source lang="text">
Name=
Version=
PlatformClass=
Resources=
ResourceFolder=
DedicatedClassLoader=
BaseURL=
User=
Password=
</source>

The following properties has to be filled by the developer of the virtual platform:
* ''Name'' and ''Version'' are arbitrary values decided by the developer. The values will be used to match the ones reported in the profile of a package that aims to target this platform; 
* ''PlatformClass'' is the entry point to the platform functionalities. It must be a subclass of <em>org.gcube.vremanagement.virtualplatform.model.TargetPlatform</em>
* ''Resources'' and ''ResourceFolder'' are both used to select the resources belonging the platform. These resources will be loaded on the classpath created for managing the platform;
* ''DedicatedClassLoader'' is a boolean flag (then allowed values are true or false) stating if a dedicated Java classloader must be created for the platform;

The last three properties have to be filled by the Site Manager that configure an instance of the virtual platform and their role is to bridge it with the concrete platform. All of them are optional:
* ''BaseURL'' is the runtime network entrypoint of the platform;
* ''User and ''Password'' are the credentials to access to the concrete platform.

== Managing platforms ==


=== Instantiating ===

A virtual platform can be instantiated starting from its configuration object. The list of configuration objects available on the node can be obtained by invoking the <em>listAvailablePlatforms()</em> method on the Platforms class. Starting from a given folder, the method reads and loads all the platform [[Virtual_Platform#Configuration|configuration files]].

<source lang="java">
import org.gcube.vremanagement.virtualplatform.image.PlatformConfiguration;
import org.gcube.vremanagement.virtualplatform.image.VirtualPlatform;
import org.gcube.vremanagement.virtualplatform.image.Platforms;



List<PlatformConfiguration> configurations = Platforms.listAvailablePlatforms(new File(GHNContext.getContext().getVirtualPlatformsLocation()));
for (PlatformConfiguration config : configurations){
   VirtualPlatform vp = new VirtualPlatform(config)
   //plays with the platform
}
</source>

=== Playing with the platform ===

=== Managing Packages ===

==== Deployment ====

==== Activation ====

==== Deactivation ====

==== Undeployment ====