Re: <array> of namevalues

[Ke Jin]

Braney wrote in http://code.google.com/p/pococapsule/issues/detail?id=7#makechanges
> The file "pococpp-iocdsm-dev-guide102.pdf" mentions that <array> can have
> type "namevalue" but doesn't really say more than that about how to use it.
> I know that <item> can have "name" and "value" attributes, but it is not
> at all clear how my code is supposed to access that information.
>

<array> of namevalue was largely introduced for PocoCapsule internal
use (CORBA integration). However, its usage should be self-explained.
Namely, it will pass the argument as two parameters. The first one (as
in the case of other array types) is the count of the array. The
second parameter is the array itself. The array element in this case
is a struct with two 'const char*' fields. By default, the struct type
id is POCO_NameValue (defined in poco.h). User can override this
definition with another struct with different type name, as long as it
has the name and value fields.

Without using this feature, the same feature (actually, support more
generic name-value) can also be achieved using DSM (similart to how
<map>, <list> are supported in pococapsule). Therefore, this feature
wasn't documented in detail.

> It would be nice if an example was included in the documentation that shows>
> how to use an array of type="namevalue", and how PocoCapsule turns that
> into invocation code. For example, I tried creating such an array, and was
> surprised to see the proxy code referring to a type called
> "POCO_NameValue", which never seemed to be mentioned in the documentation.
>

POCO_NameValue is defined in poco.h.

> If this issue would be better as a forum discussion, I will be happy to
> participate.

Yes. Very appreciate for allowing me forward to the forum.

Ke

[Bryan Raney]

Hi Ke,

Please see my inline comments...

On Sun, Mar 8, 2009 at 10:23 PM, Ke Jin <kji...@gmail.com> wrote:
>
> Braney wrote in http://code.google.com/p/pococapsule/issues/detail?id=7#makechanges
>> The file "pococpp-iocdsm-dev-guide102.pdf" mentions that <array> can have
>> type "namevalue" but doesn't really say more than that about how to use it.
>> I know that <item> can have "name" and "value" attributes, but it is not
>> at all clear how my code is supposed to access that information.
>>
>
> <array> of namevalue was largely introduced for PocoCapsule internal
> use (CORBA integration). However, its usage should be self-explained.
> Namely, it will pass the argument as two parameters. The first one (as
> in the case of other array types) is the count of the array. The
> second parameter is the array itself. The array element in this case
> is a struct with two 'const char*' fields. By default, the struct type
> id is POCO_NameValue (defined in poco.h). User can override this
> definition with another struct with different type name, as long as it
> has the name and value fields.
>
> Without using this feature, the same feature (actually, support more
> generic name-value) can also be achieved using DSM (similart to how
> <map>, <list> are supported in pococapsule). Therefore, this feature
> wasn't documented in detail.

Thank you for the explanation. I was just suggesting that this
information be included in the PDF file
(pococpp-iocdsm-dev-guide102.pdf), because (to me anyway) it was not
so obvious. There was an example of <array type="string"> in the PDF,
and there is a code example for std::map, but <array type="namevalue">
seemed to be missing details. If this is intended to be an internal
feature, then perhaps it should not be mentioned in the PDF.

>
>> It would be nice if an example was included in the documentation that shows>
>> how to use an array of type="namevalue", and how PocoCapsule turns that
>> into invocation code.  For example, I tried creating such an array, and was
>> surprised to see the proxy code referring to a type called
>> "POCO_NameValue", which never seemed to be mentioned in the documentation.
>>
>
> POCO_NameValue is defined in poco.h.

Yes, but I didn't even know POCO_NameValue existed, so I didn't know
to look for it, or where to find it. Also, poco.h says at the top
"this header file is used by generated proxy file", but if I use
<array type="namevalue"> in my setup.xml, then I need to include
poco.h in *my* code (not just the generated proxy code) in order to
interface with the data described in setup.xml. So, in some ways,
POCO_NameValue is a type internal to the library, and in other ways,
it is exposed as a type to be used by clients (like POCO_AppEnv).
Again, it just seems like it would be nice if this was pointed out in
the PDF.

Anyway, I'm not saying anything is wrong with this feature, just that
I came across the "namevalue" concept, thought it might be useful, but
it was unclear to me what to do with it. Having more information in
the developer's guide PDF would have helped me understand it better.

-- Bryan Raney (braney)

[Ke Jin]

Bryan,

Thanks for your input. We are on the same page. I am also thinking
this feature shouldn't be mentioned in the PDF. Additon considerations
are:

1. Name-value pair arraies used in most plain old C++ applications are
not necessary string-string pairs in general.

2. it is very rare that methods on plain-old c++ objects would support
the function prototype that is mandated by this kind of array (Hence,
users would have to write wrapper functions anyway when use it.)

3. there are better generic alternatives supported (based on DSM),
therefore, I would rather deprecate this feature.

This feature was written into the doc, I guess, by a mistake or some
kind of decision change during the original process.

Thanks again!
Ke

On Mar 13, 9:40 am, Bryan Raney <bra...@gmail.com> wrote:
> Hi Ke,
>
> Please see my inline comments...
>
>
>

> On Sun, Mar 8, 2009 at 10:23 PM, Ke Jin <kjin...@gmail.com> wrote:
>
> > Braney wrote inhttp://code.google.com/p/pococapsule/issues/detail?id=7#makechanges