<commit_before>RFC 0040: Annotation-based XML marshalling/unmarshalling
========================================================================
$Id$

@authors: friebe
@created: Thu Oct 20 17:31:22 CEST 2005
@status: draft
@category: xml

Scope of Change
---------------
A new API will be created to map XML to objects (and vice versa) by means
of annotations.


Rationale
---------
Be able to deserialize any XML document.


Functionality
-------------

1) Unmarshalling
~~~~~~~~~~~~~~~~
Consider the following XML:

<pre>
  <dialog id="file.open">
    <caption>Open a file</caption>
  </dialog>
</pre>

This can be mapped to a dialog object by declarting the following class:

<?php
  class Dialog extends Object {
    var
      $id       = '',
      $caption  = '';

    #[@xmlmapping(element= '@id')]
    function setId($id) {
      $this->id= $id;
    }

    #[@xmlfactory(element= '@id')]
    function getId() {
      return $this->id;
    }

    #[@xmlmapping(element= 'caption')]
    function setCaption($caption) {
      $this->caption= $caption;
    }

    #[@xmlfactory(element= 'caption')]
    function getCaption() {
      return $this->caption;
    }
  }
?>

...and using the following script:
<?php
  $dialog= &Unmarshaller::unmarshal($xml, 'Dialog');
  echo 'Unmarshalled XML= ', xp::stringOf($dialog);
?>

2) Marshalling
~~~~~~~~~~~~~~
Assuming we've declared the class as above, the following sourcecode will
create XML from the object:

<?php
  $dialog= &new Dialog();
  $dialog->setId('file.open');
  $dialog->setCaption('Open a file');

  $xml= Marshaller::marshal($dialog);
  echo 'Marshalled object= ', xp::stringOf($xml);
?>


Security considerations
-----------------------
n/a


Speed impact
------------
n/a


Dependencies
------------
n/a


Related documents
-----------------
- Castor
  http://castor.org/xml-mapping.html

- PHP 5 version
  http://xp-framework.info/xml/xp.en_US/news/view?10

Comments
--------
n/a


<EOF><commit_msg>- Set status to discussion<commit_after>RFC 0040: Annotation-based XML marshalling/unmarshalling
========================================================================
$Id$

@authors: friebe
@created: Thu Oct 20 17:31:22 CEST 2005
@status: discussion, ends Thu Nov 10 13:56:18 CET 2005
@category: xml

Scope of Change
---------------
A new API will be created to map XML to objects (and vice versa) by means
of annotations. Also, the package "xml.xp" will be deprecated.


Rationale
---------
Be able to deserialize any XML document and serialize objects to any XML.


Functionality
-------------

1) Unmarshalling
~~~~~~~~~~~~~~~~
Consider the following XML:

<pre>
  <dialog id="file.open">
    <caption>Open a file</caption>
  </dialog>
</pre>

This can be mapped to a dialog object by declarting the following class:

<?php
  class Dialog extends Object {
    var
      $id       = '',
      $caption  = '';

    #[@xmlmapping(element= '@id')]
    function setId($id) {
      $this->id= $id;
    }

    #[@xmlfactory(element= '@id')]
    function getId() {
      return $this->id;
    }

    #[@xmlmapping(element= 'caption')]
    function setCaption($caption) {
      $this->caption= $caption;
    }

    #[@xmlfactory(element= 'caption')]
    function getCaption() {
      return $this->caption;
    }
  }
?>

...and using the following script:
<?php
  $dialog= &Unmarshaller::unmarshal($xml, 'Dialog');
  echo 'Unmarshalled XML= ', xp::stringOf($dialog);
?>

2) Marshalling
~~~~~~~~~~~~~~
Assuming we've declared the class as above, the following sourcecode will
create XML from the object:

<?php
  $dialog= &new Dialog();
  $dialog->setId('file.open');
  $dialog->setCaption('Open a file');

  $xml= Marshaller::marshal($dialog);
  echo 'Marshalled object= ', xp::stringOf($xml);
?>


Security considerations
-----------------------
n/a


Speed impact
------------
n/a


Dependencies
------------
n/a


Related documents
-----------------
- Castor
  http://castor.org/xml-mapping.html

- PHP 5 version
  http://xp-framework.info/xml/xp.en_US/news/view?10

Comments
--------
- friebe, Thu Nov 10 11:56:43 CET 2005
  What's a good package name for this new API?

<EOF>
{'fraction_non_alphanumeric': 0.2217391304347826, 'fraction_numerical': 0.015942028985507246, 'mean_word_length': 2.9176915799432357, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 21}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6296204', 'n_tokens_mistral': 1376, 'n_tokens_neox': 1269, 'n_words': 382}