add description of the interfaces

Author: gregor-j

Diff for: index.md

@@ -80,6 +80,7 @@ Too short? Confused? You should probably read the documentation. 😉
     - [Configure the SAP remote function call](saprfc-function)
 * [DateTime conversions for SAP](datetime)
 * [Docker images with SAP modules](docker)
+* [Implementing PHP/SAP using the interfaces](interfaces.md)
 
 [koucky]: http://saprfc.sourceforge.net/ "SAPRFC extension module for PHP"
 [harding]: https://github.com/piersharding/php-sapnwrfc "SAP RFC Connector using the SAP NW RFC SDK for PHP"

Diff for: interfaces-api.md

@@ -0,0 +1,13 @@
+## API
+
+* The `IApi` interfaces manages the elements of the remote function.
+* `IApiElement` defines an element of an API with attributes all elements have in common: name, type, direction, and optional-flag.
+* `IValue`, `IStruct`, and `ITable` all add a `cast()` method for typecasting.
+* `IStruct` and `ITable` contain a list of `IMember` members.
+* `IMember` is a member of `IStruct` or `ITable` and only has name and type attributes.
+
+[![API interfaces](res/interfaces-api.svg)](res/interfaces-api.svg)
+
+---
+
+[Go back to the interfaces overview](interfaces)

Diff for: interfaces-config.md

@@ -0,0 +1,11 @@
+## Configuration
+
+* `IConfiguration` Defines methods for configuration management and (un)serialization. It configures connection parameters, that are common to both connection types (A, and B).
+* `IConfigA` Configure connection parameters for SAP remote function calls using a specific SAP application server (type A).
+* `IConfigB` Configure connection parameters for SAP remote function calls using load balancing (type B).
+
+[![Configuration Interfaces](res/interfaces-config.svg)](res/interfaces-config.svg)
+
+---
+
+[Go back to the interfaces overview](interfaces)

Diff for: interfaces-exceptions.md

@@ -0,0 +1,15 @@
+## Exceptions
+
+* `ISapException` A generic parent exception in order to catch SAP remote function call exceptions in general.
+* `IArrayElementMissingException` In case the API description of the SAP remote function call defines a member element in an `IArray` that is not present in the given data.
+* `IConfigKeyNotFoundException` In case a requested configuration key is missing.
+* `IConnectionFailedException` The connection to the remote SAP system failed.
+* `IFunctionCallException` In case the SAP remote function call failed for some reason.
+* `IIncompleteConfigException` The connection configuration doesn't contain all the necessary parameters.
+* `IUnknownFunctionException` The SAP remote function cannot be found using the given connection parameters.
+
+[![Exceptions](res/interfaces-exceptions.svg)](res/interfaces-exceptions.svg)
+
+---
+
+[Go back to the interfaces overview](interfaces)

Diff for: interfaces-function.md

@@ -0,0 +1,26 @@
+## Function
+
+There are three ways to create a function instance:
+
+1. Factory method: `create()` which takes all necessary information via its parameters.
+2. Decoding a formerly JSON encoded function instance using `jsonDecode()`.
+3. The constructor accepts an associative array created from `json_decode()` of a formerly JSON encoded function instance.
+
+* The `IFunction` interface defines how functions are handled:
+  * `create()` is a factory method creating a function instance.
+  * `extractApi()` queries the SAP remote function for its API circumventing the internal cache.
+  * `getApi()` returns the API of the SAP remote function and caches the result.
+  * `getConfiguration()` returns the configuration used to connect to the SAP system.
+  * `getName()` the SAP remote function name.
+  * `getParams()` returns an array of SAP remote function call parameters set by `setParams()`.
+  * `invoke()` invokes the SAP remote function call and returns its result.
+  * `resetParams()` removes any SAP remote function call parameters set by `setParams()`.
+  * `setApi()` manually sets the API of the SAP remote function.
+  * `setConfiguration()` sets the configuration used to connect to the SAP system.
+  * `setParams()` sets an array of SAP remote function call parameters.
+
+[![API function](res/interfaces-function.svg)](res/interfaces-function.svg)
+
+---
+
+[Go back to the interfaces overview](interfaces)

Diff for: interfaces.md

@@ -0,0 +1,29 @@
+## Interfaces
+
+The following PHP/SAP interfaces are available in namespace `phpsap\interfaces`. See the [php-sap/interfaces repository on github][interfaces].
+
+### Configuration
+
+The configuration interfaces are used to describe connection configuration parameters and their (un)serialization. They are separated into a generic configuration management interface, a common SAP configuration, that contains connection parameters that are common to both connection types (A and B), and connection type specific SAP configuration.
+
+[Continue to the configuration interfaces...](interfaces-config)
+
+### API
+
+The API interfaces are used to describe the API of the SAP remote function. They are separated by their number of attributes. An element, has only type and name attributes, while a value adds a direction and an optional flag and an array adds Sub-members which can only be elements.
+
+[Continue to the API interfaces...](interfaces-api)
+
+### Exceptions
+
+The exception interfaces are used to describe the result of methods in case of errors. They are all children to the overall `ISapException` which should make it easy to generally catch exceptions. Please keep in mind, to throw `InvalidArgumentException` or `LogicException` in case of programming errors as they have nothing to do with the SAP remote function call.
+
+[Continue to the exception interfaces...](interfaces-exceptions)
+
+### Function
+
+The function interface is used to describe how a SAP remove function call is created and invoked.
+
+[Continue to the function interface...](interfaces-function)
+
+[interfaces]: https://github.com/php-sap/interfaces "Interfaces for implementing the PHP/SAP API."

Diff for: res/interfaces-api.svg

@@ -0,0 +1,59 @@
+@startuml
+
+!theme plain
+top to bottom direction
+skinparam linetype ortho
+
+class IApi {
+   getInputElements():
+   getOutputElements():
+   add(element):
+   getTables():
+   getChangingElements():
+}
+class IApiElement {
+   getDirection():
+   isOptional():
+   getType():
+   getName():
+}
+class IJsonSerializable {
+   __construct(array):
+   jsonDecode(json):
+}
+class IMember {
+   __construct(array):
+   create(type, name):
+   cast(value):
+   getType():
+   getName():
+}
+class IStruct {
+   __construct(array):
+   create(name, direction, isOptional, members):
+   getMembers():
+   cast(value):
+}
+class ITable {
+   __construct(array):
+   create(name, direction, isOptional, members):
+   getMembers():
+   cast(value):
+}
+class IValue {
+   __construct(array):
+   create(type, name, direction, isOptional):
+   cast(value):
+}
+class JsonSerializable {
+   jsonSerialize():
+}
+
+IApi               -[#008200,plain]-^  IJsonSerializable
+IApiElement        -[#008200,plain]-^  IJsonSerializable
+IJsonSerializable  -[#008200,plain]-^  JsonSerializable
+IMember            -[#008200,plain]-^  IJsonSerializable
+IStruct            -[#008200,plain]-^  IApiElement
+ITable             -[#008200,plain]-^  IApiElement
+IValue             -[#008200,plain]-^  IApiElement
+@enduml