xp-framework/rfc — Issue #93: xml.meta 
Author: thekid
Created: 2011-10-17 15:53:31+00:00
State: closed
Labels: framework, implemented

Scope of Change
====
The xml.meta API will be extended to include a way to marshal objects
to trees instead of only to strings, and unmarshal XML from streams.

Rationale
====
* Performance improvement over Tree::fromString(Marshaller::marshal())
* Use the tree / node objects for further modification
* Performance improvement over Unmarshaller::unmarshal(Streams::readAll())

Functionality
====
The current API is used statically, marshalling to strings and
unmarshalling from strings.

Example
----

```php

```

The new functionality will no longer work statically and will use
different method names, `marshalTo()` instead of `marshal()`
and `unmarshalFrom()` instead of `unmarshal()`.

Examples
----

```php
marshalTo(new Node('dialog'), new DialogType());

// Integration with formresult (scriptlet API)
$m->marshalTo($response->addFormResult(new Node('dialog')), new DialogType());
}

with ($u= new Unmarshaller()); {

// Unmarshaller parses from an input source
$dialog= $u->unmarshalFrom(
new StreamInputSource($stream, '(stream)'),
'de.thekid.dialog.DialogType'
);

// From a string
$dialog= $u->unmarshalFrom(
new StringInputSource('')
'de.thekid.dialog.DialogType'
);
}
?>
```

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
The old methods including the static usage will be deprecated but will
continue to work.

Related documents
====
* http://java.sun.com/webservices/docs/1.5/api/javax/xml/bind/package-summary.html
Package javax.xml.bind
* http://xp-framework.net/rfc/contrib/rfc0093.diff
Implementing patch (skeleton)
* http://xp-framework.net/rfc/contrib/rfc0093-ports.diff
Implementing patch (ports)