Merge "Core Developer's Guide"

Author: inocybe-jenkins

manuals/developers-guide/src/main/asciidoc/core/APIdesignPrinciples_SB.adoc

@@ -0,0 +1,132 @@
+== API design principles and patterns contributed by southbound plugins
+
+This section is intended to define common design patterns supporting extensions contributed by southbound plugins, which could be used in the SAL or or used in modelling any abstract extensible APIs.
+
+NOTE: Wire protocol specific information (serialization, serialization constants , TLV identifiers, bit masks, field ordering) should not be part of the SAL. Also, APIs (interfaces, classes) should support extensibility using subclassing or other extension patterns. This allows for abstract APIs and also for concrete APIs to coexist in the SAL and to use common infrastructure.
+
+=== Extensible enumeration pattern
+
+This pattern is suitable for modelling or defining APIs for the enumeration of immutable data or types, which for example could represent ether type, protocol type, and others. The workflow for API definition is simple:
+
+. Define a simple interface with the needed functionality.
+
+. Declare an enum implementing the interface where the enum constants represent the known values.
+
+. (optional) Include a factory method mapping from names to objects implementing the interface.
+
+For more information, see the following links:
+
+** http://jtechies.blogspot.com/2012/07/item-34-emulate-extensible-enums-with.html
+
+** http://blogs.oracle.com/darcy/entry/enums_and_mixins
+
+=== Type-value pairs pattern
+
+This pattern is suitable for modelling or defining APIs for extensible set of fields, where the values could be of different types. The requirements for type-value pairs are: Extensible and Type safety.
+
+==== Common antipatterns
+
+This pattern is to replace the following constructs:
+
+
+* Simple untyped approach to properties (pros: extensible, cons: does not provide semantics and type safety):
+
+[literal]
+// Ommited for clarity...
+HashMap<String,Object> properties;
+
+
+* More refined approach using the enumeration to define a set of supported field types (pros: provides semantics, cons: not extensible).
+
+[literal]
+enum Type {
+  TYPE1(String.class),
+  TYPE2(Boolean.class),
+  private Class<?> valueType; // This line is optional.
+  // ommited for clarity... 
+}
+class Field {
+  Type type;
+  Object value;
+  // ommited for clarity...
+}
+
+
+=== Actual pattern
+
+We can model this by using the abstract class and the generics to define value type and set of subclasses representing various types of fields. The instances of this class represents actual type-value pair, where class represents type and value is represented by object in the instance.
+
+[literal]
+abstract class Field<V> {
+   private V value;
+   public Field(V value) {
+      this.value = value;
+   }
+   ...
+}
+ class Type1Field extends Field<String> {
+  public Type1Field(String value){super(value);}
+}
+ class Type2Field extends Field<Boolean> {
+  public Type2Field(Boolean value){super(value);}
+}
+
+The abstract class does not have to only define fields or values, but could also define additional methods (concrete or abstract) which could provide additional semantic about the field type. This example shows only one value field, but it is possible to have multiple fields. It is possible to model common part of API also as an interface and leave all the implementation to the super types. Map, which should store one instance of the field is: Map<Class<? extends Field<?>>,Field<?>>. It is possible to provide simpler facade on top of this map.
+
+=== Extension interface pattern
+
+The following Java design allows an object to be extended without changing its interface to clients. The object can implement additional extension interfaces. Clients can ask the object for extension interfaces that it implements.
+
+
+In the interface present in the SAL models general approach or abstraction, the client code (applications) could ask for extension interface (which could be used to model protocol specific functionality, interfaces, data) by querying for the extension. Extension is identified by Java interface (the client code using extension must be compiled against this interface).
+
+
+This pattern could be also used as an replacement for the field pattern. We have defined a set of fields provided by extension as separate class or interface, the values could be queried by using the extension class.
+The strong point of this pattern is that the client code needs to be aware of the extension and its contract (be compiled against the base interface and also extension) in order to use the extension. The code which was not compiled against extension is not affected by introducing new extensions.
+
+*Synopsis: Original pattern*
+
+[literal]
+public interface A {
+   // Ommited for clarity...
+  <T> T getExtension(Class<T> extensionType)
+}
+
+*Synopsis: Updated pattern*
+[literal]
+public interface Extensible<P> {
+   // Ommited for clarity...
+  <T extends Extension<P>> T getExtension(Class<T> extensionType)
+}
+public interface Extension<T> {
+}
+
+Where:
+
+* Extensible is interface which is to be implemented by classes which provides extension support
+
+* P - generic argument, usually interface / class which implements
+
+* Extension is marker interface (for type-safety reasons) which marks interfaces / classes which are extensions
+
+* T - generic argument, pointing to the class / interface to which this extension is associated.
+
+=== Usage example
+
+[literal]
+ublic class Node extends Extensible<Node> {
+  // contents ommited
+  // the instatiated version of extension interface isExtension method is
+  @Override
+  <T extends Extension<Node> T getExtension(Class<T> extensionType) {
+    // contents ommited
+  }
+}
+public class OpenflowNode extends Extension<Node> {
+   // contents ommited
+}
+Node node = provider.getNode(); // sample call returning node
+OpenflowNode ofNode = node.getExtension(OpenflowNode.class);
+if(ofNode != null) {
+  // do openflow specific stuff
+}

manuals/developers-guide/src/main/asciidoc/core/ODL-controller-library-descriptions.adoc

@@ -0,0 +1,123 @@
+== OpenDaylight controller library descriptions
+
+Shared functions and methods are compiled and bundled into libraries. This page describes client libraries.
+
+=== C client library
+
+The C module generates the source code for the ANSI-C-compatible data structures and (de)serialization functions that can be used in conjunction with http://xmlsoft.org/[libxml2] to (de)serialize the REST resources as they are represented as XML data.
+
+
+The generated C source code depends on the http://xmlsoft.org/html/libxml-xmlreader.html[XML Reader API] and the http://xmlsoft.org/html/libxml-xmlwriter.html[XML Writer API] as well as the <time.h>, <string.h>, and <stdlib.h> C standard libraries.
+
+
+=== REST XML example
+
+[literal]
+ #include <full.c>
+ //...
+  xmlTextReaderPtr reader = ...; //set up the reader to the url.
+ full_ns0_edgeProps *response_element = ...;
+ response_element = xml_read_full_ns0_edgeProps(reader);
+  //handle the response as needed...
+  //free the full_ns0_edgeProps
+ free_full_ns0_edgeProps(response_element);
+ 
+ 
+=== .NET client library
+
+The .NET client-side library defines the classes that can be (de)serialized to/from XML. This is useful for accessing the REST endpoints that are published by this application.
+
+==== REST example
+
+[literal]
+ //read a resource from a REST url
+ Uri uri = new Uri(...);
+ XmlSerializer s = new XmlSerializer(
+   typeof( EdgeProps )
+ );
+    //Create the request object
+ WebRequest req = WebRequest.Create(uri);
+ WebResponse resp = req.GetResponse();
+ Stream stream = resp.GetResponseStream();
+ TextReader r = new StreamReader( stream );
+  EdgeProps order = (EdgeProps) s.Deserialize( r );
+  //handle the result as needed...
+  
+This bundle contains C# source code.
+
+=== Java client library
+
+The Java client-side library is used to access the Web service API for this application.
+The JAX-WS client-side library is used to provide the set of Java objects that can be serialized to/from XML using https://jaxb.dev.java.net/[JAXB]. This is useful for accessing the REST endpoints that are published by this application.
+
+
+==== REST example (Raw JAXB)
+
+[literal]
+  java.net.URL url = new java.net.URL(baseURL + "/{containerName}");
+ JAXBContext context = JAXBContext.newInstance( EdgeProps.class );
+ java.net.URLConnection connection = url.openConnection();
+ connection.connect();
+ Unmarshaller unmarshaller = context.createUnmarshaller();
+ EdgeProps result = (EdgeProps) unmarshaller.unmarshal( connection.getInputStream() );
+ //handle the result as needed...
+ 
+ 
+==== REST example (Jersey client)
+
+[literal]
+</nowiki>
+com.sun.jersey.api.client.Client client = com.sun.jersey.api.client.Client.create();
+EdgeProps result = client.resource(baseUrl + "/{containerName}")
+   .get(EdgeProps.class);
+//handle the result as needed... 
+</nowiki>
+
+=== Java JSON client library
+
+The Java client-side library is used to provide the set of Java objects that can be serialized to/from JSON using Jackson. This is useful for accessing the JSON REST endpoints that are published by this application.
+
+==== REST example (Raw Jackson)
+
+
+[literal]
+ java.net.URL url = new java.net.URL(baseURL + "/{containerName}");
+ ObjectMapper mapper = new ObjectMapper();
+ java.net.URLConnection connection = url.openConnection();
+ connection.connect();
+  EdgeProps result = (EdgeProps) mapper.readValue( connection.getInputStream(), EdgeProps.class );
+ //handle the result as needed...
+ 
+ 
+=== Objective C Client library
+
+The Objective C module generates the source code for the Objective C classes and (de)serialization functions that can be used in conjunction with http://xmlsoft.org/[libxml2] to (de)serialize the REST resources as they are represented as XML data.
+
+
+The generated Objective C source code depends on the http://xmlsoft.org/html/libxml-xmlreader.html[XML Reader API] and the http://xmlsoft.org/html/libxml-xmlwriter.html[XML Writer API] as well as the base OpenStep foundation classes.
+
+==== REST XML example
+
+[literal]
+ #import <full.h>
+ //...
+  FULLNS0EdgeProps *responseElement;
+ NSData *responseData; //data holding the XML from the response.
+ NSURL *baseURL = ...; //the base url including the host and subpath.
+ NSURL *url = [NSURL URLWithString: @"/{containerName}" relativeToURL: baseURL];
+ NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:url];
+ NSURLResponse *response = nil;
+ NSError *error = NULL;
+ [request setHTTPMethod: @"GET"];
+  //this example uses a synchronous request,
+ //but you'll probably want to use an asynchronous call
+ responseData = [NSURLConnection sendSynchronousRequest:request returningResponse:&response  error:&error];
+ FULLNS0EdgeProps *responseElement = [FULLNS0EdgeProps readFromXML: responseData];
+ [responseElement retain];
+  //handle the response as needed...
+ 
+
+ 
+ 
+ 
+