% !TEX encoding = IsoLatin

The RESTful web service allows to store and retrieve informations about the infrastructure on which our tool is operating.
It permits to manage physical/logical topology and filtering policies given by the security administrator.

The REST resource classes are implemented in the \code{it.polito.policyorchestration.rest.resources} package and all the classes in the package will be loaded into the \textit{Jersey} servlet at startup.

To manage HTTP requests, a \code{PolicyOrchestrationService} object is injected into resources every time a REST method is called. It is responsible to maintain synchronization between requests, avoiding race conditions.

\subsection{Architecture}

The \code{PolicyOrchestrationService} contains the \code{InfrastructureManager} object and the \code{LifecycleManager} as attributes. The former contains all the object that represent the infrastructure (e.g. \code{Deployment}, \code{Landscape}, \code{Entities}, etc.), the latter offers the methods to manage the lifecycle of the program.

This class offers the following methods:
	
\begin{itemize}
	\item 
	\code{public PolicyOrchestrationService(InfrastructureManager infrastructureManager)}\newline
	it is the constrcutor method that has \code{InfrastructureManager} as parameter in input;
	
	\item \code{public synchronized void start()}\newline
	it starts the rule distribution process. It starts with an initialization of all the infrastructure elements (e.g. physical hosts, virtual switches, etc.) inserting some traffic redirection to allow filtering operations. The it starts the distribution process, optimizing rule positions and finally inserting them;	
	
	\item\code{public synchronized void shutdown()}\newline
	this method allows to close the program with the cleaning of all the rules injected;
	
	\item
	\code{public synchronized void setDeployment(Deployment d)}\newline
	\code{public synchronized void setLandscape(Landscape l)}\newline
	\code{public synchronized void setSelectorTypes(SelectorTypes s)}\newline
	\code{public synchronized void setEntities(Entities e)}\newline
	these methods are the "setters" for the \code{InfrastructureManager Object};
	
	\item
	\code{public synchronized void getDeployment(Deployment d)}\newline
	\code{public synchronized void getLandscape(Landscape l)}\newline
	\code{public synchronized void getSelectorTypes(SelectorTypes s)}\newline
	\code{public synchronized void getEntities(Entities e)}\newline
	these methods are the "getters" for the \code{InfrastructureManager Object};
	
	\item
	{\ttfamily public synchronized DeploymentElement getDeploymentElement(boolean onlyNet-\newline workNodes, UriInfo root)}\newline
	this method creates the \code{DeploymentElement} from the loaded \code{Deployment}, there are also the same method for \code{PhysicalHostElement}, \code{VirtualSwitchElement} and \code{ServiceNodeElement};
	
	\item
	\code{public synchronized Deployment loadDeployment(DeploymentElement root)}\newline
	this method initialize the \code{Landscape} object;
	
	\item
	{\ttfamily public synchronized LandscapeElement getLandscapeElement(String type, UriInfo\newline root)}\newline
	this method creates the \code{LandscapeElement} from the loaded \code{Landscape}, there are also the same method for \code{LandscapeHostElement} and \code{LandscapeServiceElement};
	
	\item
	\code{public synchronized Landscape loadeLandscape(LandscapeElement net)}\newline
	this method initialize the \code{Landscape} object;
	
	\item
	{\ttfamily public synchronized EntitiesElement getEntitiesElement(boolean onlyISP, UriInfo\newline root)}\newline
	this method creates the \code{EntitiesElement} from the loaded \code{Entities}, there are also the same method for \code{EntityElement} and \code{RuleElement};
	
	\item
	\code{public synchronized Entities loadEntities(EntitiesElement ent)}\newline
	this method initialize the \code{Entities} object;
	
	\item
	{\ttfamily public synchronized FilteringPoints getFilteringPoints(String type, UriInfo root)}\newline
	this method creates the \code{FilteringPointsElement} from the loaded FilteringPoints, there are also the same method for \code{ExclusionElement} and \code{MiddleBoxElement};
	
	\item
	\code{public synchronized void loadFilteringAndExclusions(FilteringPoints fp)}\newline
	this method updates the environment according to file passed as parameter, it set filtering point (VM that acts as router and packet filter) and it sets the excluded physical topology elements;
	
	\item
	\code{public synchronized DistributionOutcome getDistributionOutput()}\newline
	this method returns the output of the distribution process.
	
\end{itemize}


\subsection{Modify the tool}
To implement new REST methods, it is necessary to add an API on the preferred resource path. All the operation on the \code{InfrastructureManager} data should be executed in \code{PolicyOrchestrationService} class in a \code{synchronized} context to preserve the correct concurrency.
For example, if we want to implement methods to add/remove a virtual switch from the \code{Deployment} element, we need to add a method in the \code{DeploymentResources} class, that handles the \hput, \hdelete requests. Then is necessary to implement in the \code{PolicyOrchestrationService} class the method to add/remove a virtual switch from the \code{Deployment} element loaded in \code{InfrastructureManager} object.