Piccolo XML processor - Revision history

Akivela at 12:44, 23 August 2011

2011-08-23T12:44:37Z

Akivela: /* Basic Statements */

2008-03-04T16:09:24Z

‎Basic Statements

Akivela at 16:08, 4 March 2008

2008-03-04T16:08:56Z

Olli: /* XMLParamAware classes */

2007-01-24T11:28:14Z

‎XMLParamAware classes

Olli: /* Using methods, constructors and fields */

2007-01-24T11:25:54Z

‎Using methods, constructors and fields

Olli: /* Using methods, constructors and fields */

2007-01-24T11:21:47Z

‎Using methods, constructors and fields

Olli: /* XML Processor Class Map */

2007-01-24T11:12:46Z

‎XML Processor Class Map

Olli: /* XML Processor Class Map */

2007-01-24T11:07:05Z

‎XML Processor Class Map

Olli at 10:19, 24 January 2007

2007-01-24T10:19:15Z

Olli at 09:10, 24 January 2007

2007-01-24T09:10:56Z

← Older revision		Revision as of 12:44, 23 August 2011
Line 1:		Line 1:
		+	'''This documentation is deprecated! Although the functionality is still in Wandora application, the piccolo_sample_web_app has been removed from Wandora distribution packages.'''
		+
	Piccolo XML processor is a kind of scripting language in xml format that is used to configure Piccolo applications. The language is based and interpreted on Java and you can do nearly anything you could do in normal Java classes.		Piccolo XML processor is a kind of scripting language in xml format that is used to configure Piccolo applications. The language is based and interpreted on Java and you can do nearly anything you could do in normal Java classes.

@@ Line 9: / Line 9: @@
 <action xp:class="org.wandora.piccolo.actions.ViewTopic"/>
 <service xp:idref="wandora"/>
-<logger xp:id="logger" xp:class="com.gripstudios.piccolo.SimpleLogger"/>
+<logger xp:id="logger" xp:class="org.wandora.piccolo.SimpleLogger"/>
 First example creates a new instance of the specified class, the second instance refers to a variable named ''wandora'' in the symbol table of the processor but does nothing with that (we will return to this later, why would you actually want to do this). The third example creates a new instance of a logger and stores it in the symbol table with variable name ''logger''. ''xp:class'' attribute is used to create new classes, ''xp:idref'' to refer to variables in the symbol table and ''xp:id'' to store variables in the symbol table. Note that the element names "action", "service" and "logger" do not refer to any class names or variables in symbol table or anything else for that matter.

@@ Line 7: / Line 7: @@
 In following examples ''xp:'' prefix refers to ''http://www.gripstudios.com/xmlparamprocessor'' xml namespace.
-<action xp:class="com.gripstudios.applications.wandora.actions.ViewTopic"/>
+<action xp:class="org.wandora.piccolo.actions.ViewTopic"/>
 <service xp:idref="wandora"/>
 <logger xp:id="logger" xp:class="com.gripstudios.piccolo.SimpleLogger"/>
@@ Line 26: / Line 26: @@
 Next example passes two parameters for the constructor of ''WandoraService''.
-<service xp:id="wandora" xp:class="com.gripstudios.applications.wandora.WandoraService">
+<service xp:id="wandora" xp:class="org.wandora.piccolo.WandoraService">
    <param xp:idref="logger"/>
    <param xp:class="com.gripstudios.piccolo.XMLProperties" >
@@ Line 52: / Line 52: @@
 <map xp:idref="this" xp:method="mapClass">
    <node>template</node>
-   <class>com.gripstudios.piccolo.VelocityTemplate</class>
+   <class>org.wandora.piccolo.VelocityTemplate</class>
 </map>
@@ Line 70: / Line 70: @@
 |  string     ||   java.lang.String
 |-
-|  properties ||   [[com.gripstudios.piccolo.XMLProperties]]
+|  properties ||   [[org.wandora.piccolo.XMLProperties]]
 |}
 Using class map and ''XMLParamAware'' classes you can hide much of the "code" in the configuration file and make it look like an ordirany xml configuration file. However currently these features are not used as much is possible.

@@ Line 40: / Line 40: @@
 == XMLParamAware classes ==
-Another peculiarity in the previous example is the parameters on lines 4 and 5. According to what has been said so far it would look like on the line 4 a new ''String'' is created with two ''String'' parameters. But ''String'' class does not contain such a constructor. In fact, something completely different happens here. The ''MapParser'' class implements a certain interface called ''XMLParamAware''. Whenever an object of a class that implements this interface is created, the contents of the element are not parsed and passed to the constructor. Instead a constructor with no parameters is used to create the object and then ''xmlParamInitialize'' method of the newly created object is called. This method receives as its parameters the xml element used to create the object and the xml processor itself. The method may then process the contents of the element in any way whatsoever and initialize the object.
+Let's look at the lines 4 and 5 of previous example again. According to what has been said so far it would look like on the line 4 a new ''String'' is created with two ''String'' parameters. But ''String'' class does not contain such a constructor. In fact, something completely different happens here. The ''XMLProperties'' class implements a certain interface called ''XMLParamAware''. Whenever an object of a class that implements this interface is created, the contents of the element are not parsed and passed to the constructor. Instead a constructor with no parameters is used to create the object and then ''xmlParamInitialize'' method of the newly created object is called. This method receives as its parameters the xml element used to create the object and the xml processor itself. The method may then process the contents of the element in any way whatsoever and initialize the object.
-Some classes may require a very large, possibly variable, number of parameters and properties to initialize properly. It would be very inconvevient to create constructors for such classes. These kinds of classes should implement ''XMLParamAware'' interface. Often classes that are initialized this way still use the xml processor to process at least some subelements individually. For example the class in previous example creates a ''Properties'' object that maps keys to values. Each ''key'' and ''value'' element is processed with the xml processor and could could refer to symbol table with ''xp:idref'', create new objects etc. instead of creating simple strings.
+Some classes may require a very large, possibly variable, number of parameters and properties to initialize properly. It would be very inconvevient to create constructors for such classes. These kinds of classes should implement ''XMLParamAware'' interface. Often classes that are initialized this way still use the xml processor to process at least some subelements individually. For example the class in previous example creates a ''Properties'' object that maps keys to values. Each ''key'' and ''value'' element is processed with the xml processor and could refer to symbol table with ''xp:idref'', create new objects etc. instead of creating simple strings.
 This is also one of the exceptions when element names do matter. The class may process the contents of the element in any way and thus can process elements differentely depending on the element name. For example the Piccolo ''Application'' class registers services with ''service'' element name, parses action map, templates and properties from ''actionmap'', ''templates'' and ''properties'' elements respectively and adds each object with ''contextobject'' element name to the Velocity context.

@@ Line 34: / Line 34: @@
 </service>
-First parameter is a logger that is retrieved from the symbol table and second parameter is the return value of the invocation of ''getProperties'' method of a newly created instance of ''MapParser'' class. Let's look at lines 3 to 6 in more detail. Are the parameters on lines 4 and 5 passed for the constructor or the ''getProperties'' method? If both ''xp:class'' and ''xp:method'' are present then the contents of the element are passed to the constructor and the method is called without any parameters. If you wanted to create a new instance without parameters and call a method with parameters you would have to do it with two elements, first create a new instance and store it in the symbol table and then refer to the stored object and call the method.
+First parameter is a logger that is retrieved from the symbol table and second parameter is a new instance of ''XMLProperties'' class.
 == XMLParamAware classes ==

@@ Line 28: / Line 28: @@
 <service xp:id="wandora" xp:class="com.gripstudios.applications.wandora.WandoraService">
    <param xp:idref="logger"/>
-   <param xp:class="com.gripstudios.piccolo.MapParser" xp:method="getProperties">
+   <param xp:class="com.gripstudios.piccolo.XMLProperties" >
      <property><key>wandora.projectfile</key><value>C:/wandora/WEB-INF/classes/base.wpr</value></property>
      <property><key>wandora.projectfile.autoupdate</key><value>true</value></property>

@@ Line 1: / Line 1: @@
 Piccolo XML processor is a kind of scripting language in xml format that is used to configure Piccolo applications. The language is based and interpreted on Java and you can do nearly anything you could do in normal Java classes.
 Each xml element either creates a new instance of some class, retrieves a variable from the symbol table of the processor or invokes a method of an object. Usually element names are completely insignificant and attributes and the structure defines the behaviour. Thus element names are chosen to be somewhat descriptive of what is being done. There are a few exceptions which will be described later.
@@ Line 11: / Line 13: @@
 First example creates a new instance of the specified class, the second instance refers to a variable named ''wandora'' in the symbol table of the processor but does nothing with that (we will return to this later, why would you actually want to do this). The third example creates a new instance of a logger and stores it in the symbol table with variable name ''logger''. ''xp:class'' attribute is used to create new classes, ''xp:idref'' to refer to variables in the symbol table and ''xp:id'' to store variables in the symbol table. Note that the element names "action", "service" and "logger" do not refer to any class names or variables in symbol table or anything else for that matter.
-You can also use methods with the ''xp:method'' attribute
+== Using methods, constructors and fields ==
-<map xp:idref="this" xp:method="mapClass">
+You can use methods with the ''xp:method'' attribute and public varibles of objects with ''xp:field'' attribute. You can also use static methods and fields of classes. To do this specify the class with ''xp:static'' attribute and then use ''xp:method'' to invoke a method or ''xp:field'' to access a public variable. For example:
-   <node>template</node>
-   <class>com.gripstudios.piccolo.VelocityTemplate</class>
-</map>
-Here the method ''mapClass'' of the object in the symbol table with a variable name ''this'' is called (''this'' usually contains the xml processor itself). All subelements are processed and passed as parameters for methods or constructors when using ''xp:class'' attribute. In this case two ''String'' parameters are passed for the method. Unless nothing else is specified elements will behave as if they contained 'xp:class="java.lang.String"'. When creating new ''String''s or objects in ''java.lang'' package that wrap primitive Java types (such as ''java.lang.Integer''), the contents of the element are read as a string literal instead of subelements being parsed. This string is then given as the only parameter for the constructor. Note that all Java classes that wrap a primitive type have a constructor with a single string parameter. The second line in the example is in Java 'new java.lang.String("template")'.
+<object xp:id="out" xp:static="java.lang.System" xp:field="out"/>
 Next example passes two parameters for the constructor of ''WandoraService''.
@@ Line 32: / Line 36: @@
 First parameter is a logger that is retrieved from the symbol table and second parameter is the return value of the invocation of ''getProperties'' method of a newly created instance of ''MapParser'' class. Let's look at lines 3 to 6 in more detail. Are the parameters on lines 4 and 5 passed for the constructor or the ''getProperties'' method? If both ''xp:class'' and ''xp:method'' are present then the contents of the element are passed to the constructor and the method is called without any parameters. If you wanted to create a new instance without parameters and call a method with parameters you would have to do it with two elements, first create a new instance and store it in the symbol table and then refer to the stored object and call the method.
-Another peculiarity is the parameters on lines 4 and 5. According to what has been said so far it would look like on the line 4 a new ''String'' is created with two ''String'' parameters. But ''String'' class does not contain such a constructor. In fact, something completely different happens here. The ''MapParser'' class implements a certain interface called ''XMLParamAware''. Whenever an object of a class that implements this interface is created, the contents of the element are not parsed and passed to the constructor. Instead a constructor with no parameters is used to create the object and then ''xmlParamInitialize'' method of the newly created object is called. This method receives as its parameters the xml element used to create the object and the xml processor itself. The method may then process the contents of the element in any way whatsoever and initialize the object.
+== XMLParamAware classes ==
 Some classes may require a very large, possibly variable, number of parameters and properties to initialize properly. It would be very inconvevient to create constructors for such classes. These kinds of classes should implement ''XMLParamAware'' interface. Often classes that are initialized this way still use the xml processor to process at least some subelements individually. For example the class in previous example creates a ''Properties'' object that maps keys to values. Each ''key'' and ''value'' element is processed with the xml processor and could could refer to symbol table with ''xp:idref'', create new objects etc. instead of creating simple strings.
 This is also one of the exceptions when element names do matter. The class may process the contents of the element in any way and thus can process elements differentely depending on the element name. For example the Piccolo ''Application'' class registers services with ''service'' element name, parses action map, templates and properties from ''actionmap'', ''templates'' and ''properties'' elements respectively and adds each object with ''contextobject'' element name to the Velocity context.