<commit_before>\documentclass[a4paper, 10pt]{article}
\usepackage[utf8]{inputenc}
%\usepackage[brazil]{babel}
\usepackage[top=3cm,left=3cm,right=2cm,bottom=2cm]{geometry} % para as margens
\usepackage{graphicx} % para as figuras  
\usepackage{color}
\usepackage[hidelinks]{hyperref}
\usepackage{listings}

\newcommand{\ee}{CHOReOS Enactment Engine}


\title{\ee\ REST API \\ {\normalsize Version 1.1}}
\author{<NAME> (IME - USP)}

\begin{document}

\maketitle

\section{Introduction}

This document provides detailed information about the \ee\ REST API. 
Understanding the API enables you to write your own code to enact a choreography.
Although the CHOReOS Dynamic Development Process automates the \ee\ invocation at the end of the Synthesis Process, writing your own client may be a good idea when you already have designed the choreography at the service interaction level and have chosen the concrete services. 

This document is organized as follows. Section \ref{sec:model} presents the data model that defines XML representations exchanged by API messages. Section \ref{sec:api} describes all the operations provided by the REST API, detailing parameters and return structures. Section \ref{sec:client} presents our client implementation that can be used within any Java program.

\section{Data model}
\label{sec:model}

As in any API, \ee\ operations receive and return complex data structures representing real world concepts. 
Figure \ref{img:data_model} presents these concepts in the UML notation.
Although the REST API handles XML representations, we use here the UML notation, since it makes easier to the reader to understand the concepts.

\begin{figure}
\centering
\includegraphics[scale=0.75]{img/data_model.pdf}
\caption{\ee\ REST API data model}
\label{img:data_model}
\end{figure}

We proceed with a brief explanation about each class:

\begin{description}
\item [ChorSpec:] represents what the middleware needs to know to enact a choreography;
\item [ServiceSpec:] represents what the middleware needs to know to deploy a service (with one or more instances for load balancing).
\item [ServiceDependency:] represents dependencies among services (if \verb!service A! invokes \verb!service B!, we say \verb!service A! depends on \verb!service B!);
\item [Choreography:] provides information about a choreography instance; 
\item [Service:] provides information about a deployed service. 
\item [ServiceInstance:] provides information about a specific instance, or replica, of a deployed service. 
\end{description}

To request a choreography enactment, it is important to understand very well the \verb!ServiceSpec! class. Therefore, the description of each one of its attributes follows:

\begin{description}
\item [name:] a unique name within the choreography specification;
\item [owner:] the organization that holds the infrastructure where the service must be deployed (not implemented, for now a single cloud per \ee\ instance is supported);
\item [group:] services in the same group will be deployed in the same cloud node (not implemented);
\item [roles:] list of roles implemented by the service;
\item [dependencies:] list of \verb!ServiceDependency! entries; each entry describes the name of the dependency (matching the \verb!name! attribute), and the the role provided by the dependency;
\item [type:] whether the service is a SOAP service or a REST service. More types can be added as necessary.
\item [packageType:] the type of the deployable artifact, according to the \verb!PackageType! enumeration\footnote{When the package type is COMMAND\_LINE the service will be executed by the ``java -jar'' command.};
\item [packageUri:] the location of the binary file to be deployed. If type is LEGACY (services that are not being deployed specifically for this choreography, but are already available somewhere), this attribute will represent the complete service endpoint;
\item [port:] the TCP port used by the service. Note that multiple replicas of a single service will all use the same port. Mandatory if type is COMMAND\_LINE;
\item [endpointName:] the endpoint suffix after deployment. For example, if the service will be deployed as \verb!http://<some_ip>/choreos/service!, the endpoint is \verb!choreos/service!. Note that multiple replicas of a single service will all use the same endpoint. If type is LEGACY, endpoint is empty.
\item [version:] the service version, which is used by the \ee\ to define which services must be redeployed in a choreography update.
\item [numberOfInstances:] How many instances of the service should be deployed (onto different virtual machines) in order to allow the load to be distributed.
\end{description}


\subsubsection*{More about dependencies}

In a service composition, some services depends on other services. A service that depends on other services is a \emph{consumer} service, and the service that provides functionality to the dependent service is the \emph{provider}. In simple service compositions, such dependency relations are hardcoded on consumer services. But decoupling the consumer service implementation from the actual provider endpoint is a good practice, which enables dynamic adaptation. Moreover, dependency hardcoding is not possible on cloud environments, since we do not know service addresses before deployment. Therefore, in the CHOReOS environment each consumer service is declared as depending on \emph{roles} rather than other service implementations. The consumer service must receive the actual provider endpoint of a service fulfilling the required role through the \verb!setInvocationAddress! operation, which every consumer service must implement.  

The \ee\ will use \verb!ServiceDependency! data to know which calls it must perform to the  \verb!setInvocationAddress! operation of participant services. Thus, the \ee\ will be able to tell, for example, to \verb!ServiceA! that it must use \verb!ServiceB! as \verb!Role1!, where \verb!ServiceB! is the list of endpoint URIs corresponding to the multiple instances of \verb!ServiceB!. In this way, the CHOReOS middleware provides a \emph{dependency injection}\footnote{Dependency Injection pattern, by Martin Fowler: \url{http://martinfowler.com/articles/injection.html}} mechanism to wire up service dependencies.

\emph{Obs:} to SOAP services, the URI passed to the \texttt{setInvocationAddress} operation does not contain the `\texttt{?wsdl}' suffix.

\subsubsection*{Resource impact specification}

The \verb!ServiceSpec! class has also an attribute to specify non-functional requirements, such as QoS constraints. This attribute is called ``resource impact'', and it can be used by the \verb!NodeSelector!\footnote{See the lesson Choreography Enactment.} to choose the node in which the service should be deployed. \verb!NodeSelector! will try to choose a node that enables the service to fulfil such requirements.<commit_msg>Docs updated to reflect the recent changes in the API<commit_after>\documentclass[a4paper, 10pt]{article}
\usepackage[utf8]{inputenc}
%\usepackage[brazil]{babel}
\usepackage[top=3cm,left=3cm,right=2cm,bottom=2cm]{geometry} % para as margens
\usepackage{graphicx} % para as figuras  
\usepackage{color}
\usepackage[hidelinks]{hyperref}
\usepackage{listings,enumerate}

\newcommand{\ee}{CHOReOS Enactment Engine}


\title{\ee\ REST API \\ {\normalsize Version 1.1}}
\author{<NAME> (IME - USP)}

\begin{document}

\maketitle

\section{Introduction}

This document provides detailed information about the \ee\ REST API. 
Understanding the API enables you to write your own code to enact a choreography.
Although the CHOReOS Dynamic Development Process automates the \ee\ invocation at the end of the Synthesis Process, writing your own client may be a good idea when you already have designed the choreography at the service interaction level and have chosen the concrete services. 

This document is organized as follows. Section \ref{sec:model} presents the data model that defines XML representations exchanged by API messages. Section \ref{sec:api} describes all the operations provided by the REST API, detailing parameters and return structures. Section \ref{sec:client} presents our client implementation that can be used within any Java program.

\section{Data model}
\label{sec:model}

As in any API, \ee\ operations receive and return complex data structures representing real world concepts. 
Figure \ref{img:data_model} presents these concepts in the UML notation.
Although the REST API handles XML representations, we use here the UML notation, since it makes easier to the reader to understand the concepts.

\begin{figure}
\centering
\includegraphics[scale=0.75]{img/data_model.pdf}
\caption{\ee\ REST API data model}
\label{img:data_model}
\end{figure}

We proceed with a brief explanation about each class:

\begin{description}
\item [ChoreographySpec:] represents what the middleware needs to know to enact a choreography;
\item [ServiceSpec:] a super class for common data of \verb!DeployableServiceSpec! and \verb!LegacyServiceSpec!;
\item [DeployableServiceSpec:] represents what the middleware needs to know to deploy a service (with one or more instances for load balancing); 
\item [LegacyServiceSpec:] represents an already existing service used by the choreography;
\item [ChoreographyServiceSpec:] represents a service specification along with its role within the choreography;
\item [ChoreographyServiceDependency:] represents dependencies among services (if \verb!service A! invokes \verb!service B!, we say \verb!service A! depends on \verb!service B!);
\item [Choreography:] provides information about a choreography instance;
\item [ChoreographyService:] wraps information from a \verb!Service! and a \verb!ChoreographyServiceSpec! together;
\item [Service:] a super class for common data of \verb!DeployableService! and \verb!LegacyService!;
\item [DeployableService:] provides information about a deployed service (such as the list of URIs);
\item [LegacyService:] provides information about a legacy service;
\item [ServiceInstance:] provides information about a specific instance, or replica, of a deployed service (URI, node data etc.). 
\end{description}

To request a choreography enactment, it is important to understand very well the \verb!ChoreographyServiceSpec!, \verb!ServiceSpec!, \verb!DeployableServiceSpec!, and the \verb!LegacyServiceSpec! classes. Therefore, the description of them follows:

\begin{enumerate}

\item \verb!ChoreographyServiceSpec! 
	\begin{description}
		\item [choreographyServiceUID:] a unique character sequence within the choreography specification;
		\item [owner:] the organization that holds the infrastructure where the service must be deployed (not implemented, for now a single cloud per \ee\ instance is supported);
		\item [group:] services in the same group will be deployed in the same cloud node (not implemented);
		\item [roles:] list of roles implemented by the service;
		\item [dependencies:] list of \verb!ChoreographyServiceDependency! entries; each entry describes the name of the dependency (matching the \verb!choreographyServiceUID! attribute), and the the role provided by the dependency;
		\item [serviceSpec:] the specification of the service (to be deployed or already existing) that will take this role in the choreography.
	\end{description}

\item \verb!ServiceSpec!
	\begin{description}
		\item [type:] whether the service is a SOAP service or a REST service. More types can be added as necessary.
		\item [UUID:] A randomly-generated unique identifier for the service
	\end{description}

\item \verb!DeployableServiceSpec!
	\begin{description}
		\item [packageUri:] the location of the binary file to be deployed. If type is LEGACY (services that are not being deployed specifically for this choreography, but are already available somewhere), this attribute will represent the complete service endpoint;
		\item [port:] the TCP port used by the service. Note that multiple replicas of a single service will all use the same port. Mandatory if type is COMMAND\_LINE;
		\item [endpointName:] the endpoint suffix after deployment. For example, if the service will be deployed as \verb!http://<some_ip>/choreos/service!, the endpoint is \verb!choreos/service!. Note that multiple replicas of a single service will all use the same endpoint. If type is LEGACY, endpoint is empty;
		\item [version:] the service version, which is used by the \ee\ to define which services must be redeployed in a choreography update;
		\item [numberOfInstances:] How many instances of the service should be deployed (onto different virtual machines) in order to allow the load to be distributed;
		\item [resourceImpact:] General information regarding the expected type of machine needed to run the service (see \emph{Resource impact specification});
		\item [packageType:] the type of the deployable artifact, according to the \verb!PackageType! enumeration\footnote{When the package type i    s COMMAND\_LINE the service will be executed by the ``java -jar'' command.}.
	\end{description}

\item \verb!LegacyServiceSpec!
	\begin{description}
		\item [nativeUris:] The URIs for the various replicas of the service.
	\end{description}

\end{enumerate}

\subsubsection*{More about dependencies}

In a service composition, some services depends on other services. A service that depends on other services is a \emph{consumer} service, and the service that provides functionality to the dependent service is the \emph{provider}. In simple service compositions, such dependency relations are hardcoded on consumer services. But decoupling the consumer service implementation from the actual provider endpoint is a good practice, which enables dynamic adaptation. Moreover, dependency hardcoding is not possible on cloud environments, since we do not know service addresses before deployment. Therefore, in the CHOReOS environment each consumer service is declared as depending on \emph{roles} rather than other service implementations. The consumer service must receive the actual provider endpoint of a service fulfilling the required role through the \verb!setInvocationAddress! operation, which every consumer service must implement.  

The \ee\ will use \verb!ChoreographyServiceDependency! data to know which calls it must perform to the  \verb!setInvocationAddress! operation of participant services. Thus, the \ee\ will be able to tell, for example, to \verb!ServiceA! that it must use \verb!ServiceB! as \verb!Role1!, where \verb!ServiceB! is the list of endpoint URIs corresponding to the multiple instances of \verb!ServiceB!. In this way, the CHOReOS middleware provides a \emph{dependency injection}\footnote{Dependency Injection pattern, by Martin Fowler: \url{http://martinfowler.com/articles/injection.html}} mechanism to wire up service dependencies.

\emph{Obs:} to SOAP services, the URI passed to the \texttt{setInvocationAddress} operation does not contain the `\texttt{?wsdl}' suffix.

\subsubsection*{Resource impact specification}

The \verb!ServiceSpec! class has also an attribute to specify non-functional requirements, such as QoS constraints. This attribute is called ``resource impact'', and it can be used by the \verb!NodeSelector!\footnote{See the lesson Choreography Enactment.} to choose the node in which the service should be deployed. \verb!NodeSelector! will try to choose a node that enables the service to fulfil such requirements.
{'fraction_non_alphanumeric': 0.0691485917772742, 'fraction_numerical': 0.0018128844286176757, 'mean_word_length': 5.266125760649087, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2102424', 'n_tokens_mistral': 3945, 'n_tokens_neox': 3733, 'n_words': 1978}