Re: Serialization review from August

[Richard Schwarting <richard schwarting ca>]

[resending, forgot to send to gxml-list gnome org too]

Sorry for the delay in response, I'm trying desperately to finish
my Masters thesis this semester.

So, json-glib is a library for manipulating JSON (which is an
alternative to XML, it's _javascript_ Object Notation, and looks
like this: http://en.wikipedia.org/wiki/JSON ).  json-glib
offers serialization between the JSON format and GObjects. 
GXml's serialization has been intended to provide such an
implementation but between XML and GObject.  That's why I'm
focussed on keeping the APIs and functionality similar.  In
theory, we want someone to be able to just swap the format
and not worry about changing their programming methodology.
If a serialization API within GXml had the name JSON inside,
that would be confusing, since XML and JSON are different,
competing formats.

So, I'm strongly attached to keeping a simple Serialization
framework as a base offering, and then adding your additional
features (which are useful, especially for creating XML formats
like AppData) on top.  The only challenge being ensuring that
the base one is flexible enough to accommodate XOM.

I didn't fully understand before that the SerializableObjectModel
was already extending Serializable. 

So I'd like to accept into Serializable's interface
- having default_foo implementations (but with a variation on
  its modifiers, explained below)
- having different names to avoid hiding GObject ones (but
  I wonder if you'd mind having a consistent naming change,
  explained below)
- Serializable.serialize () and Serializable.deserialize ()
 
Then add the other new features to a SerializableXom/

XomSerializable
interface extending from Serializable.

That way, we retain a simple interface that's still compatible with
the other serialization API in GNOME (from json-glib), and we also
provide the extended feature set you've created for those who need
and want it.


==2 Technical Comments==

virtual vs abstract:
- how about modifiers like this:

  public virtual int foo () {
    return default_foo ();
  }
  protected virtual default_foo () {
    return 70;
  }

  Or internal instead of protected.  That way, those implementing
  Serializable don't explicitly have to do anything if they accept
  default behaviour.

init_properties:
- perhaps init_properties could also be protected (or internal)
- can not serialize () handle adding additional properties to
  ignore?

==1 Cosmetic Comment==

get_property/set_property/list_properties/find_property
- so for json-glib, they don't run into the problem of hiding
  g_object_get_property, since it's all in C.  So, let's modify the
  names!
- You're using
    get_property_value
    set_property_value
    list_serializable_properties
    find_property_spec
  Do you mind if we use changes that are specific to Serialization?
  Like
    get_property_sn
    set_property_sn
    list_properties_sn
    find_property_sn
  The motive for that is that they're more clearly analogous to their
  counterparts (and a little shorter)

==Gee and Serialization==
 
Regarding the serializable Gee types, I really appreciate those
and will try to use them soon. For my thesis, I have a
GeeSerialization class that handles serializing existing Gee
collections automatically, but it's not done yet.  That might be of
interest.

On Tue, Nov 19, 2013 at 12:02 AM, Daniel Espinosa <esodan gmail com> wrote:

2013/11/18 Richard Schwarting <richard schwarting ca>
>
> I merged a bunch of stuff into my local master this weekend, but before I push I want to ask a bunch of things, since a lot of stuff I haven't merged until I understand its motivation.  SPOILER: at the end I suggest we create a XomSerializable interface that provides the API you desire, as distinct from the existing one (which aims to be small and restrictive like json-glib's). 
>
> Unknown properties and types, errors and signals
> In Serializable you create signals for unknown type and unknown properties, that seem to correspond with a couple of the errors in SerializationError.  Is the idea for them to replace or supplement those exceptions, allowing a programmer to improvise a solution?  Or, based on its usage in SerializableTest.vala, is it supposed to replace deserialize_property ()  (the user defines their own serialization functions and connects them instead of implementing named ones in the interface?)
>
> Right now it seems a bit redundant with what {de,}serialize_property () provides. I can see that it might be useful if the types that a program uses might change and it doesn't want to have to try to recover simply from a GError (that is, the signal provides the GXmlNode node and GParamSpec spec to work with).

In a project I'm working on I need to deal with unknown nodes and properties. I mean, any node with a name not to be deserialize as GObject or properties not defined; but you want to keep, untouched them, when you serialize again.

If is redundant or not is a question I have too.

Signal for unknown nodes or properties allows to de/serialize them when some of the standard methods fails. But you're right, if you want to handle any unknown node, from the point of view of your GObject definition, you can override default implementation of a top level node to de/serialize them; but if you find them and you haven't override de/serialize, just suscribing to signal emition could be Ok, if you don't want to override them.

 
>
>
> alternate names and values: serialized_xml_node_value, node_name, property_use_nick
> property_use_nick: Why are you interested in using the nickname for the property?  I see it getting used in SerializableObjectModelTest.vala.  Is it only for SerializableObjectModel (SOM) serialization?
> node_name: With node_name, is there any particular reason why you want to change the node name from Object?  In SerializableGeeTreeMapTest.vala, the node_name () overrides are just the name of the type but in lower case, and the original type name would appear in the otype attribute anyway (<Object otype="SpaceContainer">).
> serialized_xml_node_value: is this just for SOM serialization?
>

Default implementation on SerializableObjectModel is lowercase object type's name, but in some cases, for clarity, you want to use Camel case in node's name and attributes like:

<Communication NetworkName="Principal" MHz="100" />

That's why you can use property's nick name instead of property's name (in your code network_name could be its GObject's name and its canonical name is 'network-name', then is better to use nicks ones. For 'MHz' is better to use this representation because engineering representation, but in Vala/GObject should be 'mhz' with nick name 'MHz'.

I need this feature for my project too.

 
>
> interface: virtual vs abstract methods
> You seem to prefer abstract methods with a second default implementation method over using virtual methods in the interface.  Is there any reason why?
>

Serializable have abstract methods and default implementation, implementators could use default ones or implement its own, but declare its implementation as 'virtual' (and provide a default implementation too) will help derived classes to override it and even that re-use the default implementation.

See at ObjectModel implementation, derived classes have defined its own implementation and re-use the one on ObjectModel.

I've explained this at:

https://wiki.gnome.org/Vala/Tutorial/#Mixins_and_Multiple_Inheritance

 
>
> init_properties:
> Mostly seems to set up ignored_serializable_properties and unknown_serializable_property.  Can we just do that in the property's construct {} section instead, and eliminate this? I feel like other serialization and deserialization tasks for a Serializable object can be done in {de,}serialize_object
>

If you want to ignore some other properties, you need to override init_properties and call the default implementation before, then add yours.

AFAIK you can't override construct {}.

 
>
> Naming
> I mentioned in the previous e-mail that I'm hoping to keep naming consistent with the other serialization API used in GNOME, json-glib, for a consistent experience.  I'm inclined to thus keep things like {get,set}_property, find_property and list_properties the same names.
>

If you use that, you'll hiding GObject default ones. While GObject could access any property it has, Serialization's 'properties' property allways returns the ones to be serialized. Thats why I've implemented this way, the objective is different in both cases.

 
>
> An idea
> I feel like a lot of choices in your work come down to supporting the XML Object Model style of serialization. 

This is true. But would like to share common features:

- Common Serializable interface and implementations

- Ability to ignore properties

- Create any kind of serializable; not just the ones already exists

- Handle unknown properties and nodes. Allows to serialize back them in order to avoid information/ data lost for not modeled one

- Ability to call default implementation of any method. (A virtual method is overrided and its implementation can be called inside your implementation)

- Create Serializable objects for any objects like Gee ones (already in tree). Please, pay attention that Serializable Gee objects, don't know what kind of implementation is used)

> Would you be OK if we created XomSerializable (or XOMSerializable) that embodied those?  That way, the existing Serializable work would continue to agree with json-glib's serialization approach, and would continue being minimal (things I've merged locally from your work include things like the properties blacklist, interface methods for object-level serialization instead of just property-serialization, and for serializing/transforming values by types).  The two can continue to share code and implementation (like in Serialization's serialize_object () and deserialize_object ()).
>
> If we create the XomSerializable, I'll also be fine committing just about whatever you want to it (as long as it doesn't break the API of other stuff or strangely pollute the namespace :D).  How does that sound?  We could create a subdirectory in the source tree, like gxml/xomserialization/ or gxml/xom or something.   (I've been thinking of moving serialization into its own tree already, just because of the growth of serialization files :D)

I'm lost here. When I start my implementation of Serializable interface, I saw Json just a "format" to store objects in XML, no a wrap of some existing API (I don't know what actually is any way). Then I move things to SerializableJson class to keep your work; I'm focus on Xom, but Json could take advantage of some features and just make your tests case PASS. I think that keeping an API could be done on top of serializable branch's one.

I'm focuses on provide some thing equivalent to, but at the same time better than, .NET provides, providing the possibility to create your own representation, in XML of your object. Even when the actual API in serialization branch could be better, I think that's the way GXml will be better than other libraries, including libxml2.

SerializableObjectModel or XomSerializable or SerializableXom, can bring a bridge to XML<->GObject in a transparent way.

For example AppData [1] XML format could be modeled using Xom very easy. Providing a way to read/write/modify these data using GObject classes.

Moving serializable to a directory it's fine for me.

[1] http://www.freedesktop.org/software/appstream/docs/sect-AppStream-Metadata-AppData.html

>
> Cheerio,
>    Richard
>
>
>
>
> On Sat, Nov 16, 2013 at 1:42 PM, Daniel Espinosa <esodan gmail com> wrote:
>>
>> I agree you merge with modifications. At the end tests must pass, if not I could fix them but directly on master.
>>
>> El nov 16, 2013 9:38 a.m., "Richard Schwarting" <richard schwarting ca> escribió:
>>
>>> I'm happy with a lot of it.
>>>
>>> Would you prefer if I just give you feedback and let you respond to it, or
>>> do you mind if I start merging things with modifications (API names, visibility, comments) and perhaps changing to a new branch, and then you can object or agree to things?
>>> (I feel like that second option may be faster, and save you from doing extra work)?
>>>
>>>
>>> On Sat, Nov 16, 2013 at 9:24 AM, Richard Schwarting <richard schwarting ca> wrote:
>>>>
>>>> Doing so now.  Thanks.
>>>>
>>>>
>>>> On Sat, Nov 16, 2013 at 12:23 AM, Daniel Espinosa <esodan gmail com> wrote:
>>>>>
>>>>> I'll answer your questions if you want but really prefer you review again because changes are a lot now, just make a quick check before.
>>>>>
>>>>> El nov 15, 2013 8:59 a.m., "Richard Schwarting" <richard schwarting ca> escribió:
>>>>>
>>>>>> Hi Daniel.
>>>>>>
>>>>>> Did you ever end up going over my comments from August 15th?
>>>>>> https://mail.gnome.org/archives/gxml-list/2013-August/msg00010.html
>>>>>>
>>>>>> I know that on August 19th you responded (https://mail.gnome.org/archives/gxml-list/2013-August/msg00015.html) to my August 7th e-mail.
>>>>>>
>>>>>> I asked on August 24th (https://mail.gnome.org/archives/gxml-list/2013-August/msg00020.html) whether you missed the e-mail from the 15th (above) but I haven't seen a reply yet.
>>>>>>
>>>>>>
>>>>>> If you don't want to go over the August 15th questions/concerns because they might not be out of date, I can do a new review this weekend.  If you can respond to even the August 15th review, then perhaps we can start merging this weekend.
>>>>>>
>>>>>>
>>>>
>>>
>

--
Trabajar, la mejor arma para tu superación
"de grano en grano, se hace la arena" (R) (en trámite, pero para los cuates: LIBRE)

El nov 18, 2013 10:00 a.m., "Richard Schwarting" <richard schwarting ca> escribió:

I merged a bunch of stuff into my local master this weekend, but before I push I want to ask a bunch of things, since a lot of stuff I haven't merged until I understand its motivation.  SPOILER: at the end I suggest we create a XomSerializable interface that provides the API you desire, as distinct from the existing one (which aims to be small and restrictive like json-glib's). 

Unknown properties and types, errors and signals

In Serializable you create signals for unknown type and unknown properties, that seem to correspond with a couple of the errors in SerializationError.  Is the idea for them to replace or supplement those exceptions, allowing a programmer to improvise a solution?  Or, based on its usage in SerializableTest.vala, is it supposed to replace deserialize_property ()  (the user defines their own serialization functions and connects them instead of implementing named ones in the interface?)

Right now it seems a bit redundant with what {de,}serialize_property () provides. I can see that it might be useful if the types that a program uses might change and it doesn't want to have to try to recover simply from a GError (that is, the signal provides the GXmlNode node and GParamSpec spec to work with).

alternate names and values: serialized_xml_node_value, node_name, property_use_nick

property_use_nick: Why are you interested in using the nickname for the property?  I see it getting used in SerializableObjectModelTest.vala.  Is it only for SerializableObjectModel (SOM) serialization?

node_name: With node_name, is there any particular reason why you want to change the node name from Object?  In SerializableGeeTreeMapTest.vala, the node_name () overrides are just the name of the type but in lower case, and the original type name would appear in the otype attribute anyway (<Object otype="SpaceContainer">).

serialized_xml_node_value: is this just for SOM serialization?

interface: virtual vs abstract methods

You seem to prefer abstract methods with a second default implementation method over using virtual methods in the interface.  Is there any reason why?

init_properties:

Mostly seems to set up ignored_serializable_properties and unknown_serializable_property.  Can we just do that in the property's construct {} section instead, and eliminate this? I feel like other serialization and deserialization tasks for a Serializable object can be done in {de,}serialize_object

Naming

I mentioned in the previous e-mail that I'm hoping to keep naming consistent with the other serialization API used in GNOME, json-glib, for a consistent experience.  I'm inclined to thus keep things like {get,set}_property, find_property and list_properties the same names.

An idea

I feel like a lot of choices in your work come down to supporting the XML Object Model style of serialization.  Would you be OK if we created XomSerializable (or XOMSerializable) that embodied those?  That way, the existing Serializable work would continue to agree with json-glib's serialization approach, and would continue being minimal (things I've merged locally from your work include things like the properties blacklist, interface methods for object-level serialization instead of just property-serialization, and for serializing/transforming values by types).  The two can continue to share code and implementation (like in Serialization's serialize_object () and deserialize_object ()).

If we create the XomSerializable, I'll also be fine committing just about whatever you want to it (as long as it doesn't break the API of other stuff or strangely pollute the namespace :D).  How does that sound?  We could create a subdirectory in the source tree, like gxml/xomserialization/ or gxml/xom or something.   (I've been thinking of moving serialization into its own tree already, just because of the growth of serialization files :D)

Cheerio,

   Richard

On Sat, Nov 16, 2013 at 1:42 PM, Daniel Espinosa <esodan gmail com> wrote:

I agree you merge with modifications. At the end tests must pass, if not I could fix them but directly on master.

El nov 16, 2013 9:38 a.m., "Richard Schwarting" <richard schwarting ca> escribió:

I'm happy with a lot of it.

Would you prefer if I just give you feedback and let you respond to it, or

do you mind if I start merging things with modifications (API names, visibility, comments) and perhaps changing to a new branch, and then you can object or agree to things?
(I feel like that second option may be faster, and save you from doing extra work)?

On Sat, Nov 16, 2013 at 9:24 AM, Richard Schwarting <richard schwarting ca> wrote:

Doing so now.  Thanks.

On Sat, Nov 16, 2013 at 12:23 AM, Daniel Espinosa <esodan gmail com> wrote:

I'll answer your questions if you want but really prefer you review again because changes are a lot now, just make a quick check before.

El nov 15, 2013 8:59 a.m., "Richard Schwarting" <richard schwarting ca> escribió:

Hi Daniel.

Did you ever end up going over my comments from August 15th?
https://mail.gnome.org/archives/gxml-list/2013-August/msg00010.html

I know that on August 19th you responded (https://mail.gnome.org/archives/gxml-list/2013-August/msg00015.html) to my August 7th e-mail.

I asked on August 24th (https://mail.gnome.org/archives/gxml-list/2013-August/msg00020.html) whether you missed the e-mail from the 15th (above) but I haven't seen a reply yet.

If you don't want to go over the August 15th questions/concerns because they might not be out of date, I can do a new review this weekend.  If you can respond to even the August 15th review, then perhaps we can start merging this weekend.