Will the non-XML C++-only APIs be marked as deprecated? From: [email protected] [mailto:[email protected]] On Behalf Of Lioy, Marcello Sent: Thursday, August 18, 2016 1:30 PM To: Josh Spain <[email protected]>; Daniel Mihai <[email protected]> Cc: [email protected] Subject: Re: [Allseen-core] Removing non-XML-based public C++ APIs
Conclusion from the WG meeting today: – Consensus is to not project the non-XML to other bindings (Java and Obj-C) but not remove these from the C++ binding – All of the bindings will expose the XML based bindings – Follow up on Java binding discussion in 8/25 meeting – it wasn’t clear how difficult it is to expose the non-XML bindings – Suggestion for the work that has already been done for Java and Obj-C is to leave the work that has been done in Gerrit, so it can be resurrected down the line if there is a desire to support that functionality From: Josh Spain [mailto:[email protected]] Sent: Tuesday, August 16, 2016 3:27 PM To: Daniel Mihai <[email protected]<mailto:[email protected]>> Cc: George Tang <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]>; [email protected]<mailto:[email protected]>; Aaron Vernon <[email protected]<mailto:[email protected]>>; Pawel Winogrodzki <[email protected]<mailto:[email protected]>>; Lioy, Marcello <[email protected]<mailto:[email protected]>>; Jorge Martinez <[email protected]<mailto:[email protected]>> Subject: RE: [Allseen-core] Removing non-XML-based public C++ APIs Thanks for the additional insight Dan. It's definitely worth a discussion Thursday. -Josh On Aug 16, 2016 5:00 PM, "Daniel Mihai" <[email protected]<mailto:[email protected]>> wrote: Discussing on Thursday sounds good. Josh, I agree the non-XML APIs are convenient. Also, that the app developers will have to create their own classes, and their classes might look similar to the ones that I think should be removed from Core. But, one difference is that AllJoyn Core developers are not responsible for maintaining those classes. For reference, the app developer on our side completed the XML parsing & construction code in a couple of days. That, plus the time to maintain that code, is a non-trivial cost for the app developers, but it doesn’t seem huge. I see tens of public methods inside PermissionPolicy.h. If Core starts deprecating a few of these methods, and perhaps adds a few more, the number of supported APIs and the supported combinations of APIs goes out of control. Another advantage of XML-based APIs should be that other language projections should be able to leverage more directly the C++ implementation. For example, my understanding is that alljoyn_objc could easier return the XML string coming out of: QStatus GetManifestTemplate(AJ_PSTR* manifestTemplateXml); but would have a harder time implementing equivalents for the methods below: QStatus GetManifestTemplate(MsgArg& rules); static QStatus MsgArgToManifestTemplate(const MsgArg& msgArg, std::vector<Rule>& rules); These language projections further add to the maintenance costs in Core. Dan From: Lioy, Marcello [mailto:[email protected]<mailto:[email protected]>] Sent: Tuesday, August 16, 2016 2:55 PM To: Josh Spain <[email protected]<mailto:[email protected]>>; Pawel Winogrodzki <[email protected]<mailto:[email protected]>> Cc: Daniel Mihai <[email protected]<mailto:[email protected]>>; George Tang <[email protected]<mailto:[email protected]>>; Aaron Vernon <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]>; Jorge Martinez <[email protected]<mailto:[email protected]>>; allseen-core <[email protected]<mailto:[email protected]>> Subject: Re: [Allseen-core] Removing non-XML-based public C++ APIs All, I am all for solving the problem the right way, so am supportive of discussion but we need to converge on a plan ASAP as we are past the API freeze time. Let's discuss in WG meeting this week. -------- Original Message -------- Subject: Re: [Allseen-core] Removing non-XML-based public C++ APIs From: Josh Spain <[email protected]<mailto:[email protected]>> Date: Aug 16, 2016, 13:00 To: Pawel Winogrodzki <[email protected]<mailto:[email protected]>> It doesn't make sense to remove the non-XML C++ APIs. Most C++ programmers will not want to be forced into building XML to do mundane things, and would normally end up writing something similar to the existing C++ API on top of the XML one. We should consider the XML APIs to be a sort of XML binding. If we need to revisit making the C++ APIs simpler that's a different topic, but let's not throw the baby out with the bath water. Regarding deprecation: you can't avoid it by merely using XML. While XML may be more graceful at deprecation of interfaces than C or C++, there is always a contract between the API and its consumer. We would still need to support old versions of the XML contract for 4 releases. -Josh [Image removed by sender.] Josh Spain, Director of Engineering, Affinegy 1705 S. Capital of Texas Hwy, Ste. 310, Austin, TX, 78746 512.535.1700<tel:512.535.1700> [email protected]<mailto:[email protected]> http://affinegy.com<http://affinegy.com/> On Tue, Aug 16, 2016 at 2:00 PM, Pawel Winogrodzki <[email protected]<mailto:[email protected]>> wrote: I confirm. My idea right now is to change that method’s signature to exactly what Claim() is using for manifests. There is also a separate one for signing both manifests and certificates in XML format. Pawel From: Daniel Mihai Sent: Tuesday, August 16, 2016 7:58 AM To: George Tang <[email protected]<mailto:[email protected]>> Cc: Aaron Vernon <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]>; Lioy, Marcello <[email protected]<mailto:[email protected]>>; Josh Spain <[email protected]<mailto:[email protected]>>; Jorge Martinez <[email protected]<mailto:[email protected]>>; allseen-core <[email protected]<mailto:[email protected]>>; Pawel Winogrodzki <[email protected]<mailto:[email protected]>> Subject: RE: [Allseen-core] Removing non-XML-based public C++ APIs InstallManifests is one of a few APIs that Pawel identified a couple days ago as “need to revisit”. Let’s discuss it in the next week or so, when Pawel is ready. I believe the most common way of installing manifests is by using Claim() – and Claim is available already: QStatus Claim(const qcc::KeyInfoNISTP256& certificateAuthority, const qcc::GUID128& adminGroupId, const qcc::KeyInfoNISTP256& adminGroup, const qcc::CertificateX509* identityCertChain, size_t identityCertChainCount, AJ_PCSTR* manifestsXmls, size_t manifestsCount); Dan From: George Tang [mailto:[email protected]] Sent: Tuesday, August 16, 2016 7:46 AM To: Daniel Mihai <[email protected]<mailto:[email protected]>> Cc: Aaron Vernon <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]>; Lioy, Marcello <[email protected]<mailto:[email protected]>>; Josh Spain <[email protected]<mailto:[email protected]>>; Jorge Martinez <[email protected]<mailto:[email protected]>>; allseen-core <[email protected]<mailto:[email protected]>> Subject: Re: [Allseen-core] Removing non-XML-based public C++ APIs Hi Dan, For these Security 2.0 changes, there are functions in SecurityApplicationproxy that don't seem to have a replacement function that uses a character pointer instead, like InstallManifests(const Manifest* manifest, size_t manifestcount) Would making manifest private make this function unusable? Thanks, George On Mon, Aug 15, 2016 at 8:48 PM, Daniel Mihai via Allseen-core <[email protected]<mailto:[email protected]>> wrote: Several months ago, we decided in the Core WG to start adding a set of new Public Security 2.0 C++ APIs, based on XML strings. For example, instead of the older: QStatus UpdatePolicy(const PermissionPolicy& policy); we added: QStatus UpdatePolicy(const char* policyXml); The older method requires having Public classes such as PermissionPolicy, Rule, Peer, Marshaller, DefaultPolicyMarshaller, Manifest, etc. These Public classes and methods are harder to maintain. For example, when Core needs to add or remove a Public method parameter, they have to go through a cumbersome Public API deprecation process, that takes years to complete. We are now ready to start moving the older, non-XML-based, methods and classes out of Public, into Private. If we succeed, a Security Manager app will not be able to use directly those classes/methods anymore. Please speak up in case you have questions or other type of feedback about this plan. (https://jira.allseenalliance.org/browse/ASACORE-2736) The XML-based APIs can be somewhat harder to use when developing a Security Manager app. For example, a Security Manager app might have to: - Parse on its own the XML string coming from GetManifestTemplate, and - Construct on its own an XML string used as parameter for UpdatePolicy At MSFT, we used msxml APIs for parsing. I guess other Security Manager vendors might use libxml2 or a similar library. If you are looking for the set of Security 2.0 C++ APIs that we expect will remain Public, please take a look at alljoyn_c\inc\alljoyn_c. The C APIs are already using just the XML APIs. Dan _______________________________________________ Allseen-core mailing list [email protected]<mailto:[email protected]> https://lists.allseenalliance.org/mailman/listinfo/allseen-core
_______________________________________________ Allseen-core mailing list [email protected] https://lists.allseenalliance.org/mailman/listinfo/allseen-core
