\chapter{Web Services Binding}

\section{Overview}

All services and operations defined in the domain model specification are presented in the Web Services binding.  

The WSDL for these services reference two XSD documents. One defines elements for the primary data types of documents, folders, relationships, policies, items, and secondary types as well as collections of these types of objects. The second XSD defines the message formats for each of the CMIS services; the messages often refer to the data types defined in the first XSD schema. The WSDL presents exactly the abstract services defined in the Services section.

The normative CMIS Web Services binding is defined by the WSDL and XSD as well as the details given here in this part of the CMIS specification.


\subsection{WS-I}

A CMIS Web Services binding MUST comply with WS-I Basic~Profile~1.1 and Basic~Security~Profile~1.0.


\subsection{Authentication}

A CMIS Web Services binding SHOULD support WS-Security~1.1 for Username~Token~Profile~1.1 and MAY also support other authentication mechanisms. A CMIS repository MAY grant access to all or a subset of the CMIS services to unauthenticated clients.


\subsection{Content Transfer}

All endpoints of the Web Services binding MUST be MTOM enabled.


\subsection{Reporting Errors}
\label{ws:reporting_errors}

Services MUST report errors via SOAP faults. The \texttt{CMIS-Messaging.xsd} defines a basic fault structure that includes an error code and an error message and the WSDL for each service defines specific messages that have the basic fault format.


\section{Web Services Binding Mapping}

The Domain Model defines all services, operations, parameters and objects of CMIS. The Web Services binding is an exact one-to-one mapping of this definition with small exceptions that are explained in the next section. Operations and parameters are named exactly after their counterparts in the Services section. All rules and exceptions defined there apply to the Web Services binding. Optional parameters and optional return values are not set if they are missing or their value is NULL.


\section{Additions to the Services section}

\subsection{updateProperties and checkIn Semantics}

This binding supports partial properties updates. All properties passed to \cmisservicelink{updateProperties} or \cmisservicelink{checkIn} will be updated to their new values. Properties that are passed without a value will be set to their default value or un-set if no default value is defined. All others property values remain untouched.

\subsection{Content Ranges}
This binding supports the retrieval of content ranges. The operation \cmisservicelink{getContentStream} accepts two optional parameters:

\begin{description}
	\item[Integer offset] The first byte of the content to retrieve. Default value is 0.
	\item[Integer length] The length of the range in bytes.  Default value is the size of the content minus the offset.
\end{description}

If the offset value is greater than the size of the content the repository SHOULD throw a constraint exception.
If offset + length is greater than the size of the content the repository should deliver the content from the offset to the end of the content.


\subsection{Extensions}
\label{ws:extension}

On all input messages and some output messages exists an element called extension. This element is used to provide vendor or repository-specific information between client and server.

All of the types referenced by the schema also support xs:any for vendor or repository-specific information. 


\subsection{Web Services Specific Structures}

This binding requires specific structures that are not part of the general CMIS schema.


\subsubsection{cmisFaultType and cmisFault}

\texttt{cmisFaultType} and \texttt{cmisFault} SHOULD be used to generate SOAP faults. 

See section~\ref{ws:reporting_errors}~\nameref{ws:reporting_errors}.


\subsubsection{cmisRepositoryEntryType}

\texttt{cmisRepositoryEntryType} is the return structure of \cmisservicelink{getRepositories}. It contains the id and the name of a repository.


\subsubsection{cmisTypeContainer}

\texttt{cmisTypeContainer} is the return structure of \cmisservicelink{getTypeDescendants}. It holds a type hierarchy.


\subsubsection{cmisTypeDefinitionListType}
\texttt{cmisTypeDefinitionListType} is the return structure of \cmisservicelink{getTypeChildren}. It contains a list of types, the hasMoreItems flag and the numItem element.

\cmisexample{webservices/getTypeChildren}


\subsubsection{cmisObjectInFolderType, cmisObjectParentsType and cmisObjectInFolderContainerType}

\texttt{cmisObjectInFolderType} holds, in addition to a \texttt{cmisObjectType} object, a path segment string. It is used in all operations that support the includePathSegments parameter. \texttt{cmisObjectParentsType} is similar but has a relative path segment string instead of a path segment. For details about path segments and relative path segments see section \ref{dm:paths}~\nameref{dm:paths}.

\texttt{cmisObjectInFolderContainerType} contains a folder hierarchy.

\cmisexample{webservices/getChildren}
\cmisexample{webservices/getDecendants}

\subsubsection{cmisObjectListType and cmisObjectInFolderListType}

\begin{sloppypar}
\texttt{cmisObjectListType} and \texttt{cmisObjectInFolderListType} hold lists of \texttt{cmisObjectType} and \texttt{cmisObjectInFolderType} structures. They also contain the hasMoreItems flag and the numItems element that are returned by operations that return these lists.
\end{sloppypar}


\subsubsection{cmisContentStreamType}

\texttt{cmisContentStreamType} wraps a content stream and additional information about the stream.


\begin{tabular}{|l|p{3.3in}|p{0.75in}|p{0.75in}|}
\hline
& & Client to Repository &Repository to Client\\
\hline
length & Length of the content stream in bytes.\newline If set, it MUST be a positive number.\newline If the length is unknown it MUST NOT be set. If it is used in the context of \cmisservicelink{appendContentStream} this is the size of the chunk in bytes. & SHOULD be set & SHOULD be set\\
\hline
mimeType & MIME Media Type of the content stream.\newline For the primary content of a document it SHOULD match the value of the property \texttt{cmis:contentStreamMimeType}. If it is used in the context of \cmisservicelink{appendContentStream} this either MUST NOT be set or MUST match the MIME Media Type of the document. If it is the first chunk it SHOULD be set and defines the MIME Media Type of the document. & SHOULD be set & MUST be set\\
\hline
filename & Filename of the content stream.\newline For the primary content of a document it SHOULD match the value of the property \texttt{cmis:contentStreamFileName}. & SHOULD be set & SHOULD be set\\
\hline
stream & The content stream.\newline MUST be present even if the content stream has 0 bytes. & MUST be set & MUST be set\\
\hline
\end{tabular}


\subsubsection{cmisACLType}

\texttt{cmisACLType} is the return structure of \cmisservicelink{getACL} and \cmisservicelink{applyACL}. It contains the current Access Control List (ACL) of the object and the exact flag that indicates if the ACL fully describes the permission of this object.

\cmisexample{webservices/getAcl}


\subsubsection{cmisExtensionType}

\texttt{cmisExtensionType} is a placeholder for extensions.  See section \ref{ws:extension}~\nameref{ws:extension}.

