Maven & xjc

Maven integration of xjc is available from a number of sources.  In this post I'll look at some examples of what is available from jvnet.

Documentation is available here: http://confluence.highsource.org/display/J2B/JAXB2+Basics+Plugins

Simple Example

    <plugin>
        <groupId>org.jvnet.jaxb2.maven2</groupId>
        <artifactId>maven-jaxb2-plugin</artifactId>
        <executions>
            <execution>    
                <goals>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <extension>true</extension>
           <schemaDirectory>src/main/resources</schemaDirectory>
           <schemaIncludes>
               <include>my_schema.xsd</include>
           </schemaIncludes>
            <generateDirectory>src/main/java</generateDirectory>
            <generatePackage>com.me.generated</generatePackage>
            <episode>false</episode>     
        </configuration>
    </plugin>

This simple example generates my_schema.xsd JAXB classes and puts them into src/main/java in the com.me.generated package.  This is pretty much the most simple example of this plugin.

Example With Catalogue File

    <plugin>
        <groupId>org.jvnet.jaxb2.maven2</groupId>
        <artifactId>maven-jaxb2-plugin</artifactId>
        <version>0.8.2</version>
        <executions>
            <execution>
                <goals>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <extension>true</extension>
            <generateDirectory>src/main/java</generateDirectory>

            <catalogs>
                <catalog>
                    <dependencyResource>            
                        <groupId>com.me.common</groupId>
                        <artifactId>xsd-project</artifactId>
                        <resource>common.catalog</resource>
                    </dependencyResource>
                </catalog>
            </catalogs>

            <episodes>
                <episode>
                    <groupId>com.me.common</groupId>
                    <artifactId>xsd-project</artifactId>
                </episode>
            </episodes>    

            <episode>true</episode> 

            <args>
                <arg>-XtoString</arg>
                <arg>-Xequals</arg>
                <arg>-XhashCode</arg>
            </args>
            <plugins>
                <plugin>
                    <groupId>org.jvnet.jaxb2_commons</groupId>
                    <artifactId>jaxb2-basics</artifactId>
                    <version>0.6.4</version>
                </plugin>
             </plugins>      
        </configuration>    
    </plugin>


This plugin will parse the available *.xsd files in the src/main/resources directory and create JAXB annotated classes in the src/main/java directory.  If an bindings.xjb is also present in the resources directory then this will be used.

generateDirectory - where to put the JAXB classes.
catalogs - These allow an xsd reference to be overridden and redirected locally or into a jar file.
episodes - This tells xjc to not create code for these xsd because it is already available.
episode - This tells xjc to generate an episode file for these xsds
args - optional arguments to add to the JAXB classes.  This requires the plugin that follows it.

Catalog File

A catalog file allows the xsd schema locations to be altered and redirected.  If a schema file has an import such as


    <xs:import namespace="http://www.me.com/common/config" />


Note there is no schemaLocation value.  This will fail the schema validation without a catalog file helping to tell xjc where the actual xsd source is.  A valid catalog file to do this would be

    PUBLIC "http://www.me.com/common/config" "maven:com.me.common:xsd-project!/config.xsd"

Here the first part of the catalog has the same namespace as the import namespace.  This is how they match. The second element can be a standard file location or, like here, a reference to an xsd in a jar which is a maven dependency.  It is only with the maven plugin that this maven:... reference will work.  Standard xjc does not recognise this notation. NOTE: there is a colon separating 'maven' from the groupId from the artifactId.  Putting a . instead will cause the catalogue redirect to not work and that can eat up time trying to find the reason why!!

Episode File

An episode file is just a standard bindings file.  It tells xjc not to create JAXB annotated classes for objects which may appear in an xsd (Not all the elements of the xsd need to be contained in an episode file although this would be a little unusual and require manually changing the episode file after generation).
This maven plugin can use episode files from other jars but can also be told to generate one using the

            <episode>true</episode> 

Common Errors

If you get a stack trace like this,

    com.sun.istack.SAXParseException2: SCD "x-schema::tns" didnt match any schema component

Then a schema is included in the episode file but never referenced.  If you can remove the episode file from the configuration then this will cure it.  Otherwise just create an empty schema which imports all the episode elements but does nothing with them.  I think this error is trying to be helpful and tell you when something is included and it doesn't need to be but the message isn't particularly clear.  Hopefully there may be an option to ignore this error in the future because an episode file may contain multiple schemas when you don't necessarily need them all.

XML Schemas / XSD

Here are a few simple memory joggers for how to create xml schema (xsd) files.

Namespaces

Namespaces are important parts of xsds.  They control the prefixes and help to remove ambiguity if there are two types which have the same name.  They are also import if you want to using binding files to create java classes in different packages for different files.

Normally a targetNamespace is defined for a schema along with a xmlns command which refers to the same targetNamespace.  The targetNamespace says that this xsd defines this namespace.  The xmlns is the same for all items but because it is the same as the targetNamespace it is satisfied by this file (it refers to itself so no import is needed).  The targetNamespace doesn't have to be included but makes it harder to extend or split up the schema later.


  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 
      xmlns:conf="http://www.mycompany.com/myapp/config" targetNamespace="http://www.mycompany.com/myapp/config">


Note that the conf and targetNamespace are the same.

ComplexType

ComplexType is very common.  It defines a link between one object that can have multiple children.  An example of a ComplexType is

    <xs:complexType name="person">
        <xs:annotation>
            <xs:documentation>
                The details about a person.
            </xs:documentation>
        </xs:annotation>
        <xs:sequence>
            <xs:element name="FirstName" type="xs:string" minOccurs="1" maxOccurs="1" />
            <xs:element name="Surname" type="xs:string" minOccurs="1" maxOccurs="1" />
            <xs:element name="Age" type="xs:int" minOccurs="0" maxOccurs="1" />
        </xs:sequence>
    </xs:complexType>


The complexType can then be referenced in another object

    <xs:element name="staff" type="person" minOccurs="0" maxOccurs="unbounded" />

and in xml the person would look like

    <Person>
        <FirstName>Fred</FirstName>
        <Surname>Bloggs</Surname>
        <Age>43</Age>
    </Person>

Enumeration

If an enumeration is being used the don't make it an anonymous one.  If this happens then the xjc parser cannot turn it into a Java enumeration but instead does some horrible string effort.  Therefore, always make enumerations proper types.


    <xs:simpleType name="YesNo">
        <xs:annotation>
            <xs:documentation>Yes or No enumeration</xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:string">
            <xs:enumeration value="YES" />
            <xs:enumeration value="NO" />
        </xs:restriction>
    </xs:simpleType>


Restrictions need to have a 'base' that is the type of all the enumerations that it includes.

Extension

One object can extend another to include extra values.  For example, the person complexType defined about in the person object can be extended,

    <xs:complexType name="ExtendedPerson" >

        <xs:annotation>

            <xs:documentation>More people details</xs:documentation>

        </xs:annotation>

        <xs:complexContent>

            <xs:extension base="person">

                <xs:sequence>

                    <xs:element name="Salutation" type="SalutationType" minOccurs="1" maxOccurs="1" />

                </xs:sequence>

            </xs:extension>

        </xs:complexContent>

    </xs:complexType>

Where SalutationType is another enumeration.  Once Java classes have been generated the ExtendedPerson class extends the Person class with salutationType being the only local variable.  So in xml

    <ExtendedPerson>
        <FirstName>Fred</FirstName>
        <Surname>Bloggs</Surname>
        <Age>43</Age>
        <SalutationType>MR</SalutationType>
    </ExtendedPerson>

Import

Sometimes it is useful to have an import from one schema into another.  This allows types to be used from different schemas.  Firstly include the xmlns for the right target into the schema header as follows,

    xmlns:com="http://www.mycompany.com/myapp/common" 

Then import a schemaLocation which tallies up to this namespace.  The import command is,

    <xs:import namespace="http://www.mycompany.com/myapp/common" schemaLocation="common.xsd"/>


Here the common.xsd must have a targetNamespace as the same as the namespace in the import statement, in this case 'http://www.mycompany.com/myapp/common'.

Binding Files

Binding files (.xjb) can be used to simplify the xjc command and create java objects in different target packages.  To use a binding file the different xsds must have different namespaces.  A binding file which allows different packages to be used could be,

    <jxb:bindings xmlns:jxb="http://java.sun.com/xml/ns/jaxb" version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema" >

        <jxb:bindings namespace="http://www.mycompany.com/myapp/common" schemaLocation="common.xsd" >

            <jxb:schemaBindings>

                <jxb:package name="com.mycompany.myapp.common"/>

            </jxb:schemaBindings>

        </jxb:bindings>

    

        <jxb:bindings namespace="http://www.mycompany.com/myapp/config" schemaLocation="config.xsd" >

            <jxb:schemaBindings>

                <jxb:package name="com.mycompany.myapp.config"/>

            </jxb:schemaBindings>

        </jxb:bindings>

    </jxb:bindings>

The binding file can be referenced using the -b command in xjc.

GlobalBindings

It is possible to have a bespoke element that needs to be parsed in a particular way.  This can be done with a globalBinding such as,

    <jxb:globalBindings fixedAttributeAsConstantProperty="true">
        <jxb:javaType name="com.my.SpecialElement" xmlType="my:specialElement"
                      parseMethod="com.my.SpecialElementAdaptor.unmarshal"
                      printMethod="com.my.SpecialElementAdaptor.marshal">
        </jxb:javaType>
    </jxb:globalBindings>

This can also be used to format standard types such as dates, although this will be global across all the schemas and will result in xjc creating Adaptors in weird packages!

    <jxb:globalBindings fixedAttributeAsConstantProperty="true">
        <jxb:javaType name="java.util.Date" xmlType="xs:dateTime"
                      parseMethod="com.my.DateTimeAdaptor.unmarshal"
                      printMethod="com.my.DateTimeAdaptor.marshal">
        </jxb:javaType>
    </jxb:globalBindings>

SchemaBindings

In the situation where there are multiple schemas in a binding file this globalBinding is unlikely to be good enough (or even work at all).  Therefore, the binding can also be included in the schema part so that the binding only applies to one schema.

    <jxb:bindings namespace="http://www.my.com/common" schemaLocation="common.xsd" >
        <jxb:schemaBindings>
            <jxb:package name="com.my.common.generated"/>
        </jxb:schemaBindings>
        <jxb:bindings node="//xs:simpleType[@name='DeletionDateTime']">  
            <jxb:javaType name="java.util.Date"
  parseMethod="com.my.DateTimeAdaptor.unmarshal"
  printMethod="com.my.DateTimeAdaptor.marshal"/>  
        </jxb:bindings>
    </jxb:bindings>

This form uses an xPath to find the correct simpleType.

    node="//xs:simpleType[@name='DeletionDateTime']"

Note that // means search everywhere in the document for a xs:simpleType with name 'DeletionDateTime'.

Both the GlobalBindings and the SchemaBindings create Adaptors which are just named Adaptor#.  This can cause name clashes when you have a hierarchy of projects (jars) which means that you can end up not using the correct adaptor.

XJC Extension & Adaptors

A further option to allow a specific adaptor to be used is to specify the adaptor that you want to use.  This can be done using the xjc extension.  Firstly you need to include the namespace in the bindings file.
    <jxb:bindings  version="2.1" xmlns:jxb="http://java.sun.com/xml/ns/jaxb" 
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc">

Next you can then use the xjc options.

    <jxb:bindings namespace="http://com.my/data" schemaLocation="my-data.xsd">
        <jxb:schemaBindings>
            <jxb:package name="com.my.data.generated" />
        </jxb:schemaBindings>
        
        <jxb:bindings node="//xs:complexType[@name='_Name_']/xs:sequence/xs:element[@name='_Date_']">
            <xjc:javaType name="org.joda.time.DateTime" adapter="com.my.data.util.JodaDateAdaptor" />    
        </jxb:bindings>
    </jxb:bindings>

xjc

xjc is bundled with java and is used to parse xsd and xjb files to create JAXB annotated java classes for a particular xml schema.  Example commands are

To parse a single file

    xjc -d myapp/java -p com.mycompany.myapp config.xsd

To parse multiple files

    xjc -d myapp/java -p com.mycompany.myapp *.xsd

To parse multiple files using a binding

    xjc -d myapp/java -b myapp.xjb *.xsd

-d = The route directory to create the classes in

-p = The package from the route directory

-b = refer to a binding file

Spring and JSON

The integration between Spring and JSON objects is very strong and can be incredibly useful from a client web app.

Spring Setup

Spring requires very little setup.  Provided the Jackson classes are on the classpath

    <dependency>
        <groupId>org.codehaus.jackson</groupId>
        <artifactId>jackson-mapper-asl</artifactId>
        <version>1.9.7</version>
        <scope>compile</scope>
    </dependency>

Then spring is basically ready to go!

Returning JSON

Returning JSON to the client is the easiest part. Just return a class or list of classes from the spring MVC controller method and it will be transformed into JSON automagically and be available to the client.  The key piece of magic here is the @ResponseBody tag which tells spring that the return value should make up the whole of the response body of the Http Response. Also the produces = .. value tells spring to use the Jackson processor because we can the application/json mime type as the output.

Here is an example


    @RequestMapping(value = "/gettopics", method = RequestMethod.GET, produces = "application/json")
    @ResponseBody
    public List<String> getTopics(final HttpServletRequest request)
    {
        final List<String> topics = new ArrayList<String>();
        topics.add("topic1");
        topics.add("topic2");

        return topics;
    }


Here the topics List object gets changed to a javascript list.  This can be processed on the client side by getting a result object

    for (var i=0; i<result.length; i++){
        alert(result[i]);
    }

And that is basically it.  Obviously your choice of javascript library to do the ajax request will have an impact here.  JQuery or Dojo would be the most common.

Accepting JSON

Accepting an json object into a Spring MVC method is a little more tricky.  Firstly you have to create an object to marshal into such as

    public class JsonExample {

        /** Value 1. */
        private final String value1;

        /** Value 2. */
        private final String value2;

        /**
         * Construct this object.  The benefit here is that this object is now immutable.

         */
        @JsonCreator
        public JsonExample(@JsonProperty("value1") final String value1,
                           @JsonProperty("value2") final String value2){
            this.value1 = value1;
            this.value2 = value2;
        }

        /**
         * Get the first value

         */

        public String getValue1(){

            return value1;

        }

    }

The annotations here tell Jackson how to marshal the JSON into this java object.  However, if you don't want an immutable object you just create getters and setters and you don't need any annotations at all! In the MVC controller method we simply have a @RequestBody rather than @ResponseBody this time and it all just works.


    @RequestMapping(value = "/settopics", method = RequestMethod.POST)
    @ResponseBody
    public void setTopics(final HttpServletRequest request, @RequestBody final JsonExample jsonExample)
    {
        ...
    }

Here the @ResponseBody seems like it should be surplus to requirements but the client doesn't like it if it isn't there.

In the web client a Javascript object is created

    var topics = {
        value1 : 'my topic',
        value2 : 'another topic'
    };

    var stringToSend = json.stringify(topics);

Again the choice of javascript library to make this call is down to the user but here the dojo/json module has been used.  The content headers need to be set on the post request


    Content-Type : 'application/json'

Posting a List of Objects

You would think that if you posted a list of object then you could just declare List<JsonExample> in the spring method but unfortunately this doesn't work.  Instead you have to declare an extension to the List object such as

    public class JsonExampleList extends ArrayList<JsonExample> {
        private static final long serialVersionUID = 3412220511906097746L;
    }

It doesn't require anything in it at all but helps Jackson sort out what you really mean and then the marshalling can continue.  Without doing this Jackson will convert to a LinkedHashMap of values and you can process this manually if you want to but the tip above will help Jackson sort it out.

Oracle Spatial

Here are a few reminders for how to do the Oracle Spatial stuff

Using a Spatial Column

To use a spatial column in a table you need to create spatial metadata and a spatial index.  In SQL Developer you can do this by right clicking on the table and choosing Spatial - Update Spatial Metadata and Spatial - Create Spatial Index.  At this point many standard tools will be able to query and display the geometry out of the box.

Tools

uDig
http://udig.refractions.net/
Displays a Oracle Spatial Geometry by just choosing the column.  It is based on the Eclipse RCP (Rich Client Platform)

Georaptor
http://sourceforge.net/projects/georaptor/
A useful plugin for SQL Developer which makes the creation of the index and metadata more simple.  It has a viewer which is available within SQL Developer.

Validating Geometry

To validate a geometry column in a table you can use

    select sdo_geom.validate_geometry(<column_name>, 0.05) from <table_name>

where 0.05 is a tolerance value.

Dojo DataGrid

Dojo has a number of table type tools that can be used.  TableContainer helps with a table layout (see http://dojotoolkit.org/reference-guide/dojox/layout/TableContainer.html) but to display a genuine table of data the DataGrid is excellent.

Links / Docs

ItemFileReadStore: http://dojotoolkit.org/reference-guide/dojo/data/ItemFileReadStore.html

ItemFileWriteStore: http://dojotoolkit.org/reference-guide/dojo/data/ItemFileWriteStore.html
DataGrid: http://dojotoolkit.org/reference-guide/dojox/grid/DataGrid.html

Require / Define

Functionality required for the DataGrid is available in the following modules.

    dojo/data/ItemFileWriteStore
    dojox/grid/DataGrid

are needed to be able to use the DataGrid.  (I have in the past had some problems with the order of the require / define and putting the DataGrid towards the end of the list seemed to cure this).

ItemFileWriteStore / ItemFileReadStore

Both of these object back the DataGrid amongst other things (Tree for example).  They are relatively easy to configure.  In the most basic form just create a JSON object of rows such as


    var hardwareList = [
        { name: 'PC',          partNo: 'PC1',     available: true,  cost: 250.00},
        { name: 'Netbook', partNo: 'N1233', available: false, cost: 150.00},
        { name: 'Tablet',     partNo: 'IP3',       available: false, cost: 550.00},
        { name: 'Phone',     partNo: 'SGS3',   available: true,  cost: 350.00}    ];

Next create a wrapper JSON object which includes the name of the identifier here it is the 'name' attribute in the JSON data but it could be any attribute. Finally create the store

    var data = {identifier: "name", items: hardwareList};
    var store = new dojo.data.ItemFileWriteStore({data: data});

DataGrid

Now that we have the data we can create the DataGrid. We need to create the layout for this grid to say which bits of data make up with columns etc


    var layout = [[
        {'name': 'Name',    'field': 'name',   'width': '100px'},
        {'name': 'Part No', 'field': 'partNo', 'width': '70px'},
        {'name': 'Cost',    'field': 'cost',   'width': '70px'}
    ]];


Here the 'name' is the column name, the 'field' is the data attribute and 'width' is the column width.  This layout can then be used in the construction of the DataGrid


    var grid = new dojox.grid.DataGrid({
                                    id: 'myDataGridId',
                                    store: store,
                                    structure: layout,
                                    onRowClick: function(e){
                                        var rowIndex = e.rowIndex;
                                        var available = grid.store.getValue(grid.getItem(rowIndex), 'available');
                                            if (available){
                                                ...
                                            }
                                    }
    });

    grid.placeAt("myDivToReplace");
    grid.startup();



Here the id is the name of the DataGrid object in the html dom.  The store is the data created earlier, and the layout is the column information above.  There are a number of event handlers which can be added and the onRowClick is shown here.  Within the onRowClick is the call

    grid.store.getValue(grid.getItem(rowIndex), 'available')

which shows how to get the correct data out of the store irrespective of the sorting that is going on.  If you just use the rowIndex on the hardwareList object then a sort on the column will give you the wrong result so this has to be used.  Finally set the grid locaion and call startup.

NOTE:  If the 'myDivToReplace' has no height then the DataGrid will have no height and not appear.  Set the height of the div you are replacing and the DataGrid will occupy that space.

Dojo Topic

Dojo provides a really useful topic based messaging system that can be used to send messages between decoupled pieces of javascript.

require / define

To use the topic functionality just include

    "dojo/topic"

at the top of the javascript file in the require or define section

Subscribe / Publish

It is really easy to use this functionality.  Firstly subscribe to a topic where the topic has a particular string name and a function to call as a result of a message,


    topic.subscribe("/log/add", function(message) {
        console.log(message);
    });


Now everytime a publish is done to the /log/add topic the function will be called.

To publish to that topic

    topic.publish("/log/add", "the message");

The publish subscribe isn't limited to one variable and can be passed multiple values.

That's really all there is to it.  The functionality is incredibly useful for larger web apps and particularly where the app code has been split into different modules and not all modules know about each other.  It helps to keep the hierarchy correct.

Dojo Mouse and Keyboard Events

Keyboard events in dojo are pretty easy for the most part!  You can just use the on() function to attach them and you are done! The on function is part of the "dojo/on" module which will need to be part of the require or define declaration.

Example to catch mouse down events on a particular dom


    on(registry.byId("myDiv"), 'mousedown', function(evt){
        console.log("Mouse Down Event");
    });


Catch keyup events on an input area.


    on(registry.byId("search"), "keyup", function(evt) {                
        doSearch(registry.byId("search").get('value'));
    });


The biggest problem arises when you want to catch a keyboard event on a dom object which doesn't normally accept keyboard input such as a div, span etc.  In this case you need to make it focusable and by far the easiest way to do that is to add a tabIndex.

    dom.byId("myDiv").tabIndex = 0; // Allow key events
    on(dom.byId("myDiv"), 'keypress', function(evt){
        console.log("KeyPress Event");
    });

You can use the dojo/keys module to check for the key value just like in Java Swing.


    if (evt.keyCode == dojo.keys.LEFT_ARROW){

    } else if (evt.keyCode == dojo.keys.RIGHT_ARROW) {

    }

Useful Tools

Here is a list of useful tools that I have come across.  I'm always forgetting what I've found so here is a list!

Development Tools

Toad
http://www.toadworld.com/
Brilliant SQL editor and database management tool.

Console
http://sourceforge.net/projects/console/
Really useful Windows Command wrapper with gives tabs, resizing, etc

MPutty
http://ttyplus.com/multi-tabbed-putty/
Manages multiple putty windows

SoapUI
http://www.soapui.org/
Tool for testing soap services.

IETester
http://www.my-debugbar.com/wiki/IETester/HomePage
Tester to allow rendering in multiple different IE versions.

SourceTree
https://www.sourcetreeapp.com/
Windows app for accessing Git repositories

Text Editors

JEdit
http://www.jedit.org/index.php?page=download
Great cross-platform tool.  Drag to select is cool as is the encoding support.

Textpad
http://www.textpad.com/
Good integration with windows.

Notepad++
http://notepad-plus-plus.org/download
Good general text editor.

Zip / Archive

7-zip
http://www.7-zip.org/
Easily the best free zipper around (IMHO!)

File Transfer

Filezilla
http://filezilla-project.org/
Free FTP file transfer tool - very good.

WinSCP
http://winscp.net/eng/index.php
Another good FTP / SFTP tool.

PC Cleanup

CCleaner
http://www.piriform.com/ccleaner/download
Cleans up temp files and scans and cleans registry.

Audio / Visual

HD Converter
www.koyotesoft.com

Converts HD formats.

Camstudio
http://camstudio.org/
Record video / audio from the activity on your computer.

GIMP
http://www.gimp.org/
GNU Image Manipulation Program.

Audacity
http://audacity.sourceforge.net/
Music file manipulation.

Virus / Malware

Malwarebytes
http://www.malwarebytes.org/
Good malware and virus scanner.

Spybot
http://www.safer-networking.org/dl/
Good spyware killer.

Sophos Anti-rootkit
http://www.sophos.com/en-us/products/free-tools/sophos-anti-rootkit.aspx
Tries to find and remote root-kits from your computer.

Dojo Layouts

There are a number of layout mechanisms in Dojo.  These allow layouts to be quite simply performed but to give great results.

ContentPane

This is a simple holder and can be used to hold any standard html or dijit widgets.  It is constructed by using,

    <div id="myContent" data-dojo-type="dijit.layout.ContentPane">

As with all widgets dojo will expand out this div into multiple layers.

Reference: http://dojotoolkit.org/reference-guide/dijit/layout/ContentPane.html for more details.

BorderContainer

The border container gives a top, bottom, left, right and center region that another pane can be added to.  This makes Headers, Menus and footers incredibly easy to create.  It works in a very similar way to the java swing BorderLayout.

    <div id="myContent" data-dojo-type="dijit.layout.BorderContainer" data-dojo-props="liveSplitters:true">
        <div id="myTop" data-dojo-type="dijit.layout.ContentPane"  data-dojo-props="region:'top', splitter:true">...</div>
        <div id="myCenter" data-dojo-type="dijit.layout.ContentPane"  data-dojo-props="region:'center'">...</div>

    </div>

Note the difference between 'Headline' and 'Sidebar' views. Headline has the top and bottom having 100% width but sidebar has the left and right having 100% height.

To allow the user to move the regions include data-dojo-props="liveSplitters:true" to the BorderContainer div and put data-dojo-props="splitters:true" on the regions you want to be able to resize.

Reference: http://dojotoolkit.org/reference-guide/dijit/layout/BorderContainer.html
Tests: http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/layout/BorderContainer.html

AccordionPane

Accordions can make very useful tools for menus or tools.  They are easy to set up in Dojo.  Create a div element of type diji.layout.AccordionContainer.  Nested within this create some ContentPane div elements and each will be an accordion tab.


    <div id="accordionContainer" data-dojo-type="dijit.layout.AccordionContainer">
        <div id="menuPane" data-dojo-type="dijit.layout.ContentPane" data-dojo-props="title: 'Menu'">
            ...
        </div>
    </div>


Reference: http://dojotoolkit.org/reference-guide/dijit/layout/AccordionContainer.html
Tests: http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/layout/AccordionContainer.html

Dojo TriStateCheckBox

The TriStateCheckBox is a relatively new addition to Dojo.  It is available in version 1.7.3 and above.  Currently it is in the dojox module.  Because it is yet to be in the standard dojo / dijit modules its style sheet is not in the standard css either.  To make it work you need to include its style sheet separately.

Links

Here are some links to the TriStateCheckBox test pages,

Latest Tests: http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/form/tests/test_TriStateCheckbox.html

Tests for version 1.7.3: http://download.dojotoolkit.org/release-1.7.3/dojo-release-1.7.3/dojox/form/tests/test_TriStateCheckbox.html

Setup

The stylesheet is required separately, such as,

    <link rel="stylesheet" type="text/css" href="http://<dojo_provider>/dojo/1.8.0/dojox/form/resources/TriStateCheckBox.css" />

Obviously you have to use a dojo provider or host the dojo css and js locally.

The require function on the page needs to have "dojox/form/TriStateCheckBox" as part of it.

    <input id="tscb" data-dojo-type="dojox.form.TriStateCheckBox" data-dojo-props='checked:true'/>

This will create a checkbox which is initially checked.

Interaction

The default checkbox has three states for the 'checked' variable.  These are true, false, and mixed.  The checkbox above is defined as checked initially.  To get or set the state just use

    registry.byId('tsch').get('checked')

    registry.byId('tsch').set('checked', 'mixed')

where the registry is the dijit registry (see http://awhite.blogspot.co.uk/2012/09/dojo-dijit-dojox-tips.html)

Mixed -> Checked

When clicking on the TriStateCheckBox in the mixed state it goes to the unchecked state by default.  If this isn't what you want you can force it to go to a checked state using the states 'cycle'.

data-dojo-props='states:["mixed", true, false]'

Dojo / Dijit / Dojox Tips

Dojo is the javascript abstraction and extension library written by IBM.  It is less popular than JQuery but has superior functionality in some regards, particularly surfaces and shapes.

Documentation

Entry Point: http://dojotoolkit.org/
Latest Reference Guide: http://dojotoolkit.org/reference-guide/
Latest API Docs: http://dojotoolkit.org/api/

GFX / SVG Tutorial (version number in link): http://dojotoolkit.org/documentation/tutorials/1.8/gfx/
GFX / SVG Reference: http://dojotoolkit.org/reference-guide/1.8/dojox/gfx.html

Widget Test Areas
http://archive.dojotoolkit.org/nightly/dojotoolkit/
(navigate to the module required then 'test' for the html page)
Eg,
http://archive.dojotoolkit.org/nightly/dojotoolkit/dijit/tests/form/test_Button.html
http://archive.dojotoolkit.org/nightly/dojotoolkit/dojox/form/tests/test_TriStateCheckbox.html

Requires Structure

Dojo uses a particular structure to define the packages which are going to be used.  This is easiest to show by example,

    <script type="text/javascript">
        require(["dojo/on", "dojo/ready", "dojo/domReady!"],
            function(on, ready) {
                ready(function() {
                    on(dojo.byId("myButton"), "click", function(evt) {
                        alert("button clicked");
                    });
                });
            }
        );
    </script>

Here the dojo packages are defined in an array as the first parameter passed to the require() function.  in the second parameter a function is defined which itself has parameters with names marrying up to the the packages imported.  Eg

    dojo/on  ->  on
    dojo/ready  -> ready

These lists can get quite big at times!

Modules

Splitting code into multiple 'modules' like dojo can be really useful.  The main code that does this is,

    <script type="text/javascript">
    dojoConfig = {
       async: true,
       isDebug: true,
       parseOnLoad: true,
       packages: [{
           name: "example",
           location: '${pageContext.request.contextPath}/resources/js/modules'
       }]
    }
    </script>

Here the ${pageContext.request.contextPath} is used rather than <c:url ...> and that is because if the server doesn't know whether cookies are supported it'll add a ;jsessionid=... on the end of the c:url and this will stop dojo resolving the modules correctly.  Therefore using the c:url request here is not a good idea.

If a file utils.js is placed in the 'location' then this can be used by referencing example/utils in the require method.

    <script type="text/javascript">
        require(["example/utils", "dojo/ready", "dojo/domReady!"],
            function(exampleUtils, ready) {


The actual utils.js file has a very similar structure to a basic dojo require except that it is a 'define' instead,

    define(["dojo", "dojo/dom", "dojo/dom-geometry", "dojo/dom-style"],
        function(dojo, dom, domGeom, domStyle) {
            variable1 = null,
            array1 = new Array(),
            arraySize = new function(){
                return array1.length;
            }
        
            return {
                arraySize : function arraySize(){
                    return arraySize();
                }
            };
        }
    );

Here the function of the module returns an object which has a method in it.  Making a call on the method in this returned object would cause a redirect to the method defined in the module itself.  This way internal 'private' functions can be created without them having scope in the return part of the module.

While the example above is fine it doesn't define an object that could be reused multiple times such as a canvas.  The example is for a module such as utils etc.

This following example has an extra layer of objects which encapsulate data

    define(["dojo", "dojo/dom", "dojo/dom-geometry", "dojo/dom-style"],
        function(dojo, dom, domGeom, domStyle) {
            myObject = {
                innerVariable : null,
                innerArray : new Array(),
                arraySize : new function(){
                    return innerArray.length;
                }
            }
        
            return {
                arraySize : function arraySize(){
                    return myObject.arraySize();
                }
            };
        }
    );

Note that object literals are used here now as we are defining the elements of the object.

Dojo style

To style items such as a button declaratively,

Watch out for the dojo version number, here it is 1.9.3

- Include the Dojo stylesheets

- Tell dojo to parse the html on load

- Include the Dojo .js file

- Set the style on the body

<html>

  <head>

    <!-- Stylesheets -->

    <link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/dojo/1.9.3/dojo/resources/dojo.css">

    <link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/dojo/1.9.3/dijit/themes/claro/claro.css">

    <link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/dojo/1.9.3/dojox/grid/resources/claroGrid.css">

    <!-- Parse on load -->

    <script>dojoConfig = {parseOnLoad: true}</script>

    <!-- Include .js -->

    <script src="http://ajax.googleapis.com/ajax/libs/dojo/1.9.3/dojo/dojo.js"></script>

  </head>

  <!-- Body class -->

  <body class="claro">

    <!-- Dojo type -->

    <Button id="myButton" data-dojo-type="dijit/form/Button">My Button</Button>

  

  </body>

</html>

byId

byId() is the main way to get an html element.

    var myComponent = dom.byId('myComponentId');

this will get the typical html element (the DOM node) where 'dom' is from the module "dojo/dom".
(see http://dojotoolkit.org/reference-guide/dojo/dom.html)

If you are using dijit to create widgets then the id specified in the original html can be used to get the javascript object rather than the HTML element.  As part of dijits creation of objects it creates a registry which links the original id to the appropriate javascript object that dijit creates.  This registry can be accessed using the module "dijit/registry" in the require or define call.  Then you simply do

    var myComponent = registry.byId('myComponentId');

(see http://dojotoolkit.org/reference-guide/dijit/registry.html)

While dojo.byId() and dijit.byId() exist they have been deprecated to the functions above.

Changing Style

For simple html elements this is really straight forward,

    domStyle.set("myHtmlElementId", "display", "block");
    domStyle.set("myHtmlElementId", "width", 100);

for dijit created items like dijit buttons this is harder because the id isn't going to be correct as dojo will have expanded the html

    require(["dojo/ready", "dojo/dom-style", "dijit/registry"],
        function(ready, domStyle, registry){
            ready(function(){
                // hide a widget with id="myThinger"
                domStyle.set(registry.byId("myThinger").domNode, "display", "none");
        });
    });

Java Regular Expressions

Regular Expressions (Regex) are a really powerful tool for doing string manipulation and searching but they can be complicated!  Here are some basics.

Pattern

Creating a Pattern object in Java is a prerequisite to getting Regex going.  This can be created using code such as

    Pattern pattern = Pattern.compile(<Regex>);
    Matcher matcher = pattern.matcher(<String to check>);
    if (matcher.matches())
    {
        // Do something
    }

or
    while (matcher.find())
    {
        String found = matcher.group()
        // Do something
    }

Basic Regex

Regular expressions normally include some of the following

• [0-9] = any of 0, 1, ..., 9 - any number of times
• [0-9a-zA-Z] = any of 0, 1, ..., 9, a, b, ..., z, A, B, ..., Z - any number of times
• [0-9]{3} = any of 0, 1, ..., 9 exactly 3 times
• [0-9]{3,6} = any of 0, 1, ..., 9 between 3 and 6 times
• [^0-9]  = any character that isn't 0, 1, ..., 9 eg negation
• . = any character one time
• .* = any character any number of times (0 or more)
• .+ = any character at least once (1 or more)
• \w = any word character
• \d = any digit character
• \s = whitespace character

Some characters need to be escaped if you want to use them in the regex itself.  These are

• {}[]().*\

Groups

Groups can be a really useful and powerful concept.  If you want to replace elements of the regex but keep some bits then groups can help you. Placing parts of the regex in normal brackets will mean that they are available as a group after the match.  For example

    regex = "(hello)(\s*world)";

will match on 'hello world' but the elements are available in group $1 and $2.  They can be obtained from the matcher (see above) using

    String firstGroup = matcher.group(1);

And similarly with a replace request such as,

    matcher.replaceAll("Goodbye$2");

would replace the matched string with Goodbye and then whatever is in group 2, which is ' world'.  This way matcher can replace elements of what has been matched.

Examples

Replace all non-standard characters

    Pattern pattern = Pattern.compile("[^a-zA-Z0-9]");
    Matcher matcher = pattern.matcher(myWeirdString);
    matcher.replaceAll("");

Match all non-standard characters using the Pattern and Matcher.  Then just call replace all to get rid of everything matched!

Thread Safety

Pattern objects are thread safe but matcher objects aren't!  From the doc...

Instances of this (Pattern) class are immutable and are safe for use by multiple concurrent threads. Instances of the Matcher class are not safe for such use.

Online Help!

These tools are really useful for checking regular expressions!
https://regex101.com/
http://rubular.com/