tutorial [s.im.pl serialization]

Getting Started:

Introduction
Java Annotated Classes

Creating Translation Scope

Generating Objective-C Header Files

Translation Scope XML File

End notes

Introduction

Here we give an example on how to generate objective-c header files from java source code. Before continuing, please make sure that you have gone through the "getting started" tutorial in java". In this example we have an annotated class definition in java that we want to move to objective-c. This tutorial will make use of the internaltranslator.cocoa in the java version of s.im.pl serialization to generate code for objective-c header files. It is not necessary that you use this translator from java, developers can write their own source code files and still use the objective-c version of s.im.pl serialization. Since java supports "annotations" (and objective-c doesn't) over class and field definitions it becomes easier to work with java and generate code for header files in objective-c. Since objective-c does not support "annotations" we will also show how you can serialize s.im.pl serialization's internal data structures which will be consumed by your objective-c code.

To view this tutorial you will need to download the entire simplTutorials, simplTranslators and ecologylabFundamental projects. Access to the ecologylab fundamental project source is available through anonymous SVN access (user: anonymous, password: anonymous).

The source for this tutorial is located under /trunk/simplTutorials/src/tutorials/

Java Annotated Classes

Below is a set of annotated Java classes similar to the one presented in the Java "getting started" tutorial. We are again using Rss feeds as the case study for this tutorial. Below are three classes decorated with Java annotations. "Rss" is the composite class which holds the version number and channel object. The channel object holds some attributes but more importantly it contains a list of items. The Item object again holds a list of the categorySets. Annotations on each object defines the semantics of how the attribute is going to be translated.

If you are having trouble understanding the annotations please refer to the technical report and the getting started tutorial in java


//Rss.java



package ecologylab.tutorials.rss;



import s.im.pl serialization.ElementState;



public class Rss extends ElementState

{

  @simpl_scalar  float    version;

  @simpl_composite    Channel    channel;



  public Rss() {}

}


//Channel.java



package ecologylab.tutorials.rss;



import java.util.ArrayList;

import ecologylab.net.ParsedURL;

import s.im.pl serialization.ElementState;



public class Channel extends ElementState

{

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) String    title;

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) String    description;

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) ParsedURL  link;

   

   @simpl_nowrap

   @simpl_collection("item") 

   ArrayList<Item>     items;

   

   public Channel() { }



   public ArrayList<Item> getItems() 

   {

     return items;

   }

}


//Item.java



package ecologylab.tutorials.rss;



import java.util.ArrayList;

import ecologylab.net.ParsedURL;

import s.im.pl serialization.ElementState;



public class Item extends ElementState

{

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) String      title;

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) String      description;

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) ParsedURL    link;

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) ParsedURL    guid;

   @simpl_scalar @simpl_hints(Hint.XML_LEAF) String      author;

   

   @simpl_nowrap

   @simpl_collection("category") 

   ArrayList<String>    categorySet;

   

   public Item() {}

}

Creating Translation Scope

We create the translation scope similar to what was done in the java getting started tutorial. We wrap the three annotated Java classes into a translation scope object and return it to the calling program. Easy!


//RssTranslations.java



package ecologylab.tutorials.rss;



import ecologylab.generic.Debug;

import s.im.pl serialization.TranslationScope;



public class RssTranslations extends Debug

{

   public static TranslationScope get()

   {

     return TranslationScope.get("rss", Rss.class, Channel.class, Item.class);

   } 

}

Generating Objective-C Header Files

Now we come to the fun part of this tutorial. We will generate objective-c code right from our Java program which we can then move to our objective-c project and start serializing and deserializing XML files with very few lines of code.

We create a CocoaTranlator object and a TranslationScope object, which is fairly straight forward. We then call the translateToObjC function on our CocoaTranslator object by supplying the destination folder and the list of classes for which we want to generate objective-c header files. In the second part, we also serialize our translation scope object which will be used by our objective-c version of ecoloyglab.xml.


public class TranslatorTutorial 

{



  public static void main(String[] args) 

  {



    /*

     * We create an instance of CocaTranslator which will translate

     * our annotated java source code to Objective-C header file.

     */

    CocoaTranslator c = new CocoaTranslator();

    

    /*

     * We create an object of Translation scope of all the java files for which,

     * We need to create the Translation Scope XML file.

     */

    TranslationScope tScope  = RssTranslations.get();

    try 

    {

      /*

       * Call translateToObjC supplied with the path where we want our header files 

       * to be generated

       */

      c.translateToObjC(new File ("/output"), tScope);

      

      /*

       * Call serialize will serialize the internal data structures of 

       * s.im.pl serialization which should be used by objective-c version s.im.pl serialization

       */

      tScope.serialize(new File("/output/rss_translationScope.xml"));

    } 

    catch (Exception e)

    {

      e.printStackTrace();

    }

  }

}

Translation Scope XML File

The following XML file shows the serialized translationScope which is the heart of the many data structures that s.im.pl serialization uses to serialize and deserialize run-time objects. It is important that we produce this data structure from our Java source code as this XML file will drive the translation processes in the objective-c version of s.im.pl serialization

<translation_scope name="rss">
	<class_descriptor described_class="ecologylab.tutorials.rss.Item"
		tag_name="item">
		<field_descriptor field="title" tag_name="title"
			type="2" scalar_type="StringType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="description" tag_name="description"
			type="2" scalar_type="StringType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="link" tag_name="link" type="2"
			scalar_type="ParsedURLType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="guid" tag_name="guid" type="2"
			scalar_type="ParsedURLType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="author" tag_name="author"
			type="2" scalar_type="StringType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="categorySet" tag_name="category_set"
			type="5" scalar_type="StringType" needs_escaping="true"
			collection_or_map_tag_name="category"></field_descriptor>
	</class_descriptor>
	<class_descriptor described_class="ecologylab.tutorials.rss.Rss"
		tag_name="rss">
		<field_descriptor field="version" tag_name="version"
			type="1" scalar_type="FloatType"></field_descriptor>
		<field_descriptor field="channel" tag_name="channel"
			type="3" element_class="ecologylab.tutorials.rss.Channel"></field_descriptor>
	</class_descriptor>
	<class_descriptor described_class="ecologylab.tutorials.rss.Channel"
		tag_name="channel">
		<field_descriptor field="title" tag_name="title"
			type="2" scalar_type="StringType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="description" tag_name="description"
			type="2" scalar_type="StringType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="link" tag_name="link" type="2"
			scalar_type="ParsedURLType" needs_escaping="true"></field_descriptor>
		<field_descriptor field="items" tag_name="items"
			type="4" collection_or_map_tag_name="item" wrapped="true"
			element_class="ecologylab.tutorials.rss.Item"></field_descriptor>
	</class_descriptor>
</translation_scope>

End notes

So that's it! We have generated objective-c header files and serialized translation scope of s.im.pl serialization. Now we are ready to open up our XCode projects and simply include these files that we generated in this tutorial. With a few additional lines of code we will be able to serialize and deserialize same XML files in objective-c!

an interface ecology lab production