Recent changes to How_to_-_XMCDA_web_services

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:21 -0000

--- v23
+++ v24
@@ -75,7 +75,7 @@

 ## Starting the service manually

-You may also start your web service programmatically by instantiating the XWSExecutor class. Methods are provided to enable easy testing, e.g. disable writing, simulate input files, etc. Refer to the javadoc for details. This is especially useful if you like unit testing. Many example tests are available from the [XMCDA-WS-Example module, refer to the [XWSServicesTest](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws-examples/src/test/java/org/decisiondeck/jmcda/xws/ws/XWSServicesTest.java?revision=158&view=markup) class. This also permits you to write your own main method to replace the one of the executor if deemed necessary. 
+You may also start your web service programmatically by instantiating the XWSExecutor class. Methods are provided to enable easy testing, e.g. disable writing, simulate input files, etc. Refer to the javadoc for details. This is especially useful if you like unit testing. Many example tests are available from the XMCDA-WS-Example module, refer to the [XWSServicesTest](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws-examples/src/test/java/org/decisiondeck/jmcda/xws/ws/XWSServicesTest.java?revision=158&view=markup) class. This also permits you to write your own main method to replace the one of the executor if deemed necessary. 

 ## More documentation

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:21 -0000

--- v22
+++ v23
@@ -71,7 +71,7 @@

 ### Example files

-The J-MCDA project also features a collection of sample XMCDA files that are correctly parsed by its parsing methods. You may want to refer to these files to know what the parsers expect, and direct the users of your web services to appropriate example files if you use the built-in parsers. 
+The J-MCDA project also features a collection of [sample XMCDA files](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda/doc/Sample%20files/) that are correctly parsed by its parsing methods. You may want to refer to these files to know what the parsers expect, and direct the users of your web services to appropriate example files if you use the built-in parsers. 

 ## Starting the service manually

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:21 -0000

--- v21
+++ v22
@@ -51,7 +51,7 @@

   * The File type. This is simply a reference to the file in the input directory given as argument to the Executor followed by the name of the file. 
   * The [InputSupplier<InputStream>](http://guava-libraries.googlecode.com/svn/tags/release09/javadoc/com/google/common/io/InputSupplier.html) type. This is an input supplier initialized to give a stream to the associated input file. 
-  * The XMCDADoc type. In this case the executor will simply read the main tag from the input file, ensure it validates, and assign the result to your field. You must do the rest. You must do the rest of the deserialization. 
+  * The XMCDADoc type. In this case the executor will simply read the main tag from the input file, ensure it validates, and assign the result to your field. You must do the rest of the deserialization. 
   * Any type corresponding to a valid XML tag in a XMCDA conformant file, as a type implementing XmlObject, or as a List (or a Collection) having as a generic argument a type implementing XmlObject. Types implementing XmlObject reflects the tag names defined in the XMCDA XSL file, with a prefixed X letter. For example, you may use XAlternatives. In this case, the executor will read the appropriate tag or tags from the corresponding file, ensure it validates, and assign the result to your field. You must do the rest of the deserialization. For example, if your input field has type List<XAlternatives>, the executor will set as its value the list of Alternatives tags read from the corresponding input file. The list is guaranteed not to be empty if the field is not marked as optional: if the input file contains no XAlternatives tag, this is considered as an invalid input and treated as indicated here below. 
   * Any built-in input type, that is, any type corresponding to a return type from one of the default input transform functions. An input transform function transform XMCDA files (or tags) to a determined type. The default functions have a name prefixed with "To" to indicate that it transforms *to* some determined type. They are collected in a [given package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/). For example, the default transform ToAlternatives reads a collection of XMCDA tags and returns a Set<Alternative>. Therefore you may use a field whose type is Set<Alternative> as an input field and you know the default transformer that will be used to read the input will be given by the class ToAlternatives. Read from the available transformers to know which field types you may use and how the parsing is done.

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:20 -0000

--- v20
+++ v21
@@ -43,7 +43,7 @@
   * The simplest way is to choose a type from the following list of types the executor knows by default how to read. 
   * The more complex way is to implement your own parser and add it to the list of parsers the executor knows (see method #getInputTransformer in XWSExecutor). Parsers are called functions and are expected to transform from an XMCDA tag, or a Collection of XMCDA tags, to a type of your choice. See for example the input transformers used by default by the executor in the [appropriate package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/), whose names start with To. If you implement supplementary transformers, please think about contributing your code to this project (or publishing it somewhere).

-The executor also sets the input and output directory to the fields annotated with @XWSInputDirectory and @XWSOutputDirectory, if these exist. When this is done and the input files have been parsed, and supposing no exception occurred while parsing, the executor executes your web service (heh), that is, the #execute() method your class implements. Supposedly, this computes some results using the input data and sets the output fields appropriately. When the execute method returns, the executor writes the output data to the corresponding output file. As with the input parsing, writing the output requires the executor to know how to transform your output field to an XMCDA conforming file. It will choose a transformer by looking at the declared field type. Here also you may use built-in types, which are those for which a transformer exists, or provide your own transformer. 
+The executor also sets the input and output directory to the fields annotated with @XWSInputDirectory and @XWSOutputDirectory, if these exist. When this is done and the input files have been parsed, and supposing no exception occurred while parsing, the executor executes your web service (heh), that is, the #execute() method your class implements. Supposedly, this computes some results using the input data and sets the output fields appropriately. When the execute method returns, the executor writes the output data to the corresponding output files. As with the input parsing, writing the output requires the executor to know how to transform each of your output fields to an XMCDA conforming file. It will choose a transformer by looking at the declared field type. Once again you may use built-in types, which are those for which a transformer exists, or provide your own transformer. 

 ### Supported input types

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:20 -0000

--- v19
+++ v20
@@ -41,7 +41,7 @@
 When the XWSExecutor executes your web service, it knows the input directory where the files lie. This is typically given as argument by the application launcher. It reads, from your @XWSInput annotated fields, the source file names. For each input, it considers the corresponding field type. This indicates the XWSExecutor what it is supposed to search for in the input file and how it should be parsed. For example, if your field type is Set<Alternative>, the executor will search in the input file for an XML tag "Alternatives". You do not need to worry about how it does the job, however. The only thing you must ensure is that the input field type you use is a type the executor knows.

   * The simplest way is to choose a type from the following list of types the executor knows by default how to read. 
-  * The more complex way is to implement your own parser and add it to the list of parsers the executor knows (see method #getInputTransformer in XWSExecutor). Parsers are called functions and are expected to transform from an XMCDA tag, or a Collection of XMCDA tags, to a type of your choice. See for example the input transformers used by default by the executor in the [appropriate package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/), whose name start with To. If you implement supplementary transformers, please think about contributing your code to this project (or publishing it somewhere). 
+  * The more complex way is to implement your own parser and add it to the list of parsers the executor knows (see method #getInputTransformer in XWSExecutor). Parsers are called functions and are expected to transform from an XMCDA tag, or a Collection of XMCDA tags, to a type of your choice. See for example the input transformers used by default by the executor in the [appropriate package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/), whose names start with To. If you implement supplementary transformers, please think about contributing your code to this project (or publishing it somewhere). 

 The executor also sets the input and output directory to the fields annotated with @XWSInputDirectory and @XWSOutputDirectory, if these exist. When this is done and the input files have been parsed, and supposing no exception occurred while parsing, the executor executes your web service (heh), that is, the #execute() method your class implements. Supposedly, this computes some results using the input data and sets the output fields appropriately. When the execute method returns, the executor writes the output data to the corresponding output file. As with the input parsing, writing the output requires the executor to know how to transform your output field to an XMCDA conforming file. It will choose a transformer by looking at the declared field type. Here also you may use built-in types, which are those for which a transformer exists, or provide your own transformer.

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:20 -0000

--- v18
+++ v19
@@ -34,7 +34,7 @@

 The @XWSInput and @XWSOutput annotations may come with a "name" field, as in the example, which gives the name of the XML file to be read from, in case of an input, or to be written, in case of an output. This must be a simple file name with no path. The web service executor will ensure the files are read and written at their expected locations. To mark an input as optional, use the field "optional" from @XWSInput. 

-To start your web service from a command line, use the main method from the class XWSExecutor and give as arguments the qualified name of your class (in our example this would be org.decisiondeck.jmcda.xws.wsXMCDAServiceCutRelation), the input directory where the input files are to be found, and the output directory where the input files will be written. 
+To start your web service from a command line, use the main method from the class XWSExecutor and give as arguments the qualified name of your class (in our example this would be org.decisiondeck.jmcda.xws.ws.XWSCutRelation), the input directory where the input files are to be found, and the output directory where the input files will be written. 

 ## How this works

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:20 -0000

--- v17
+++ v18
@@ -16,7 +16,7 @@

 Let‘s start with an example: the [CutRelation](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws-examples/src/main/java/org/decisiondeck/jmcda/xws/ws/XWSCutRelation.java?view=markup) XMCDA web service. It is not necessary to understand exactly what it does to follow this explanation, but here is a short description. The service may be described as taking a fuzzy relation as input and a cut threshold, and outputting a binary relation. If you don't know what are fuzzy relations, think in terms of matrixes: the service takes as input a matrix having Alternatives as rows and Alternatives as columns. The input matrix has, for each pairs (a1, a2), a real value between zero or one that we write V(a1, a2). The service also takes a real number known as the cutting threshold, also between zero and one, that we write C. The service then returns a matrix having Alternatives as rows and Alternatives as columns, the same set of alternatives as the input matrix, and having for each pair (a1, a2) the value one if the input matrix has V(a1, a2) > C, and the value zero otherwise. 

-As you can see, the supplementary code necessary to turn a class into a web service is minimal. This allows you to concentrate on implementing what your service should really do, in this example, cut the matrix, rather than how it should parse the input files, manage exceptions, and so on. Do not hesitate to have a look at other examples available in the same package if you wish so. Note that these examples are also available as web services and reachable from e.g. the diviz client. 
+As you can see, the supplementary code necessary to turn a class into a web service is minimal. This allows you to concentrate on implementing what your service should really do, in this example, cut the matrix, rather than how it should parse the input files, manage exceptions, and so on. Have a look at other examples available in the same package if you wish so. Note that these examples are also published as web services and are reachable from e.g. the diviz client. 

 ## Overview

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:20 -0000

--- v16
+++ v17
@@ -41,7 +41,7 @@
 When the XWSExecutor executes your web service, it knows the input directory where the files lie. This is typically given as argument by the application launcher. It reads, from your @XWSInput annotated fields, the source file names. For each input, it considers the corresponding field type. This indicates the XWSExecutor what it is supposed to search for in the input file and how it should be parsed. For example, if your field type is Set<Alternative>, the executor will search in the input file for an XML tag "Alternatives". You do not need to worry about how it does the job, however. The only thing you must ensure is that the input field type you use is a type the executor knows.

   * The simplest way is to choose a type from the following list of types the executor knows by default how to read. 
-  * The more complex way is to implement your own parser and add it to the list of parsers the executor knows (see method #getInputTransformer in XWSExecutor). Parsers are called functions and are expected to transform from an XMCDA tag, or a Collection of XMCDA tags, to a type of your choice. See for example the input transformers used by default by the executor in the [appropriate package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/), whose name start with To. If you implement supplementary transformers, please think about contributing your code to this project (or publishing it somewhere). 
+  * The more complex way is to implement your own parser and add it to the list of parsers the executor knows (see method #getInputTransformer in XWSExecutor). Parsers are called functions and are expected to transform from an XMCDA tag, or a Collection of XMCDA tags, to a type of your choice. See for example the input transformers used by default by the executor in the [appropriate package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/), whose name start with To. If you implement supplementary transformers, please think about contributing your code to this project (or publishing it somewhere). 

 The executor also sets the input and output directory to the fields annotated with @XWSInputDirectory and @XWSOutputDirectory, if these exist. When this is done and the input files have been parsed, and supposing no exception occurred while parsing, the executor executes your web service (heh), that is, the #execute() method your class implements. Supposedly, this computes some results using the input data and sets the output fields appropriately. When the execute method returns, the executor writes the output data to the corresponding output file. As with the input parsing, writing the output requires the executor to know how to transform your output field to an XMCDA conforming file. It will choose a transformer by looking at the declared field type. Here also you may use built-in types, which are those for which a transformer exists, or provide your own transformer. 

@@ -53,7 +53,7 @@
   * The [InputSupplier<InputStream>](http://guava-libraries.googlecode.com/svn/tags/release09/javadoc/com/google/common/io/InputSupplier.html) type. This is an input supplier initialized to give a stream to the associated input file. 
   * The XMCDADoc type. In this case the executor will simply read the main tag from the input file, ensure it validates, and assign the result to your field. You must do the rest. You must do the rest of the deserialization. 
   * Any type corresponding to a valid XML tag in a XMCDA conformant file, as a type implementing XmlObject, or as a List (or a Collection) having as a generic argument a type implementing XmlObject. Types implementing XmlObject reflects the tag names defined in the XMCDA XSL file, with a prefixed X letter. For example, you may use XAlternatives. In this case, the executor will read the appropriate tag or tags from the corresponding file, ensure it validates, and assign the result to your field. You must do the rest of the deserialization. For example, if your input field has type List<XAlternatives>, the executor will set as its value the list of Alternatives tags read from the corresponding input file. The list is guaranteed not to be empty if the field is not marked as optional: if the input file contains no XAlternatives tag, this is considered as an invalid input and treated as indicated here below. 
-  * Any built-in input type, that is, any type corresponding to a return type from one of the default input transform functions. An input transform function transform XMCDA files (or tags) to a determined type. The default functions have a name prefixed with "To" to indicate that it transforms *to* some determined type. They are collected in a [given package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/). For example, the default transform ToAlternatives reads a collection of XMCDA tags and returns a Set<Alternative>. Therefore you may use a field whose type is Set<Alternative> as an input field and you know the default transformer that will be used to read the input will be given by the class ToAlternatives. Read from the available transformers to know which field types you may use and how the parsing is done. 
+  * Any built-in input type, that is, any type corresponding to a return type from one of the default input transform functions. An input transform function transform XMCDA files (or tags) to a determined type. The default functions have a name prefixed with "To" to indicate that it transforms *to* some determined type. They are collected in a [given package](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda/src/main/java/org/decisiondeck/jmcda/xws/transformer/xml/). For example, the default transform ToAlternatives reads a collection of XMCDA tags and returns a Set<Alternative>. Therefore you may use a field whose type is Set<Alternative> as an input field and you know the default transformer that will be used to read the input will be given by the class ToAlternatives. Read from the available transformers to know which field types you may use and how the parsing is done. 

 ### Missing or invalid input

@@ -73,9 +73,6 @@

 The J-MCDA project also features a collection of sample XMCDA files that are correctly parsed by its parsing methods. You may want to refer to these files to know what the parsers expect, and direct the users of your web services to appropriate example files if you use the built-in parsers. 

-  
-
-
 ## Starting the service manually

 You may also start your web service programmatically by instantiating the XWSExecutor class. Methods are provided to enable easy testing, e.g. disable writing, simulate input files, etc. Refer to the javadoc for details. This is especially useful if you like unit testing. Many example tests are available from the [XMCDA-WS-Example module, refer to the [XWSServicesTest](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws-examples/src/test/java/org/decisiondeck/jmcda/xws/ws/XWSServicesTest.java?revision=158&view=markup) class. This also permits you to write your own main method to replace the one of the executor if deemed necessary.

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:20 -0000

--- v15
+++ v16
@@ -14,7 +14,7 @@

 ## Example

-Let‘s start with an example: the [CutRelation](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws-examples/src/main/java/org/decisiondeck/jmcda/xws/ws/XMCDAServiceCutRelation.java?revision=158&view=markup) XMCDA web service. It is not necessary to understand exactly what it does to follow this explanation, but here is a short description. The service may be described as taking a fuzzy relation as input and a cut threshold, and outputting a binary relation. If you don't know what are fuzzy relations, think in terms of matrixes: the service takes as input a matrix having Alternatives as rows and Alternatives as columns. The input matrix has, for each pairs (a1, a2), a real value between zero or one that we write V(a1, a2). The service also takes a real number known as the cutting threshold, also between zero and one, that we write C. The service then returns a matrix having Alternatives as rows and Alternatives as columns, the same set of alternatives as the input matrix, and having for each pair (a1, a2) the value one if the input matrix has V(a1, a2) > C, and the value zero otherwise. 
+Let‘s start with an example: the [CutRelation](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws-examples/src/main/java/org/decisiondeck/jmcda/xws/ws/XWSCutRelation.java?view=markup) XMCDA web service. It is not necessary to understand exactly what it does to follow this explanation, but here is a short description. The service may be described as taking a fuzzy relation as input and a cut threshold, and outputting a binary relation. If you don't know what are fuzzy relations, think in terms of matrixes: the service takes as input a matrix having Alternatives as rows and Alternatives as columns. The input matrix has, for each pairs (a1, a2), a real value between zero or one that we write V(a1, a2). The service also takes a real number known as the cutting threshold, also between zero and one, that we write C. The service then returns a matrix having Alternatives as rows and Alternatives as columns, the same set of alternatives as the input matrix, and having for each pair (a1, a2) the value one if the input matrix has V(a1, a2) > C, and the value zero otherwise. 

 As you can see, the supplementary code necessary to turn a class into a web service is minimal. This allows you to concentrate on implementing what your service should really do, in this example, cut the matrix, rather than how it should parse the input files, manage exceptions, and so on. Do not hesitate to have a look at other examples available in the same package if you wish so. Note that these examples are also available as web services and reachable from e.g. the diviz client.

How_to_-_XMCDA_web_services modified by Olivier Cailloux

Olivier Cailloux — Wed, 21 May 2014 21:06:20 -0000

--- v14
+++ v15
@@ -16,7 +16,7 @@

 Let‘s start with an example: the [CutRelation](http://j-mcda.svn.sourceforge.net/viewvc/j-mcda/trunk/J-MCDA/xmcda-ws-examples/src/main/java/org/decisiondeck/jmcda/xws/ws/XMCDAServiceCutRelation.java?revision=158&view=markup) XMCDA web service. It is not necessary to understand exactly what it does to follow this explanation, but here is a short description. The service may be described as taking a fuzzy relation as input and a cut threshold, and outputting a binary relation. If you don't know what are fuzzy relations, think in terms of matrixes: the service takes as input a matrix having Alternatives as rows and Alternatives as columns. The input matrix has, for each pairs (a1, a2), a real value between zero or one that we write V(a1, a2). The service also takes a real number known as the cutting threshold, also between zero and one, that we write C. The service then returns a matrix having Alternatives as rows and Alternatives as columns, the same set of alternatives as the input matrix, and having for each pair (a1, a2) the value one if the input matrix has V(a1, a2) > C, and the value zero otherwise. 

-As you can see, the supplementary code necessary to turn a class into a web service is minimal. This allows you to concentrate on implementing what your service should really do, in this example, cut the matrix, rather than how it should parse the input files, manage exceptions, and so on. You may look at other examples from the same package if you wish so. Note that these examples are not only examples but are also available as web services and reachable from e.g. the diviz client. 
+As you can see, the supplementary code necessary to turn a class into a web service is minimal. This allows you to concentrate on implementing what your service should really do, in this example, cut the matrix, rather than how it should parse the input files, manage exceptions, and so on. Do not hesitate to have a look at other examples available in the same package if you wish so. Note that these examples are also available as web services and reachable from e.g. the diviz client. 

 ## Overview