On 26 February 2014 21:00, Fraser Adams <[email protected]>wrote:
> On 26/02/14 11:43, Gordon Sim wrote: > >> On 02/25/2014 10:35 PM, Jakub Scholz wrote: >> >>> I think the QMF and the tools around it demonstrate the problem of tools >>> modeled only according to some schema. Utilities like qpid-tool allow you >>> to find the schema details about the objects/classes and their methods >>> and >>> call these methods. But if you want to use the filter in the purge method >>> of a queue object, it doesn't really tell you how should the filter >>> attribute look like. >>> >>> It is of course great to be able to save development effort and to have >>> at >>> least some tools. But the value of such tools to the end user is often >>> questionable, especially since it is often connected with missing >>> documentation. >>> >> >> You are of course correct. Sufficiently accurate and detailed >> documentation is essential in order to allow users to use any tool. >> > Absolutely!! > > I'll 'fess up now, one of the reasons that I am fairly vocal about having > something useful for the schema in the AMQP 1.0 Management specification is > because if it's not explicitly required by the specification then sure as > eggs is eggs we'll end up with no documentation, whether in Qpid (not > unheard of) or some other container implementation. It's one of those > things where a little "forcing of the hand" really won't go amiss. To be > honest I'm actually fairly agnostic about how such a schema should be > implemented and if it were in the form of say an XML file I'd probably be > OK with that, but saying that it's not compliant with AMQP 1.0 Management > without a useful description of the methods and attributes being presented > is IMHO something of a powerful statement. If vendors are forced to have > documentation to be compliant and thus be able put the little "Supports > AMQP 1.0 Management" sticker on the box and in their marketing then that's > no bad thing IMHO. > > This won't be the first time I've said that I'm not *wildly* keen on > forcing users to have to look at the container's source code in order to be > able to effectively invoke management operations, to me that doesn't seem > at all reasonable, so making the need for a schema to be available a > mandatory part of the protocol would force the issue. > > Perhaps this is an overly aggressive stance and I appear to be the only > person in the discussion so far to be advocating this. I'll take a look at > the docs for the Java Broker Management Node and the dispatch router > Management Node - oh wait ;-p I rest my case m'lud ... > > OK so I'm being a bit of a Smart Alec (sorry Rob, I know it's early days > and I'm just being cheeky!) but hopefully you see my point. > > Well I'd never expect the management node to have the answers you seek, because I aim to drive that purely off meta-data :-) There will be docs for the different types of objects, and the definitions of the attributes and operations should be common between the REST and AMQP management functions. As well as product documentation I would like us to have a more formal definition (XML, JSON, whatever...) where we also extract commonality between the various implementations we have currently and extract those into meaningful aspects which can be documented. > Another slightly facetious point I'd make on this subject is that these > guys seem to have figured that this sort of thing is ever so slightly > useful. > > http://docs.oracle.com/javase/6/docs/api/java/lang/reflect/ > package-summary.html > > And indeed if you look at: > > http://docs.oracle.com/javase/6/docs/api/java/lang/reflect/Method.html > > You can get rather a lot of useful information about method signatures. > I'd of course agree that if you have arguments that are Maps and then go on > to not describe the properties of said Map then you're back to square one. > That's actually one of the problems with QMF from my perspective - the CRUD > stuff goes so far like create name, type is fine, but the properties Map > ends up being just a bit *too* free form - can anyone point to where one > would figure out which properties to set without looking at the code? > That's kind of the point Jakub makes, but I don't think this stuff > *couldn't* be added to management-schema.xml or whatever - sure it'd get a > bit verbose if we had lots of nested Maps/Lists but that's atypical, > describing the properties Map would be really useful for people. > > So, I think meta-data is useful... if you are looking to display meta data :-) The Java Broker has a JMX management interface, and you can use a tool such as JConsole which has no prior knowledge of Qpid to "manage" the broker using it. The basic operations are fine and work OK out of the box... but what one might consider the "bespoke" operations really don't because although the meta-data exists it's really not enough to build a useable user interface... Sure the parameter is a String, but actually it has to come from a constrained type... or maybe the parameters are longs... which represent message-ids... which fine if they are obtained by clicking on messages in a GUI... less good as plain text input :-). > Actually now that I'm on a roll there's actually a standards based way of > describing this sort of thing: > > http://en.wikipedia.org/wiki/XML_Metadata_Interchange > > Quite a few UML Modelling tools use XMI to store their models so > sophisticated hierarchies *could* be described in a systematic way. > > I'd accept that this might be overkill and I'm probably getting somewhat > carried away :-D but given that it's possible to describe complex UML > models I'd suspect that describing a Management Node and a few Manageble > Entities to be possible. > > > >> A schema is a form of documentation which to be useful as such needs to >> have descriptive elements within it (rather than just types and names). >> >> In one sense the example with the purge filter highlights the fact that >> the description for that parameter is not sufficiently clear. Any form of >> documentation can suffer from the same deficiency. >> > Yes I absolutely agree, FWIW I think that the QMF management-schema.xml > tends to be pretty good, but as I say above it's let down at the last > hurdle by not having the properties part of the various methods documented. > > All I'm really arguing for is for the ability for a document such as this > to be served via an AMQP request/response so that an application can use > the information (including annotations). I quite like JSON or a Map because > they seem more natural for AMQP and modern Web Services, though I'd settle > for XML at a push. > > So, personally I think it is better to drive implementations to commonality than to say that it's a free for all and that it is enough just to be self-describing. It would surely make life easier if the Java Broker and C++ Broker used the same names and operations to perform the same tasks... better that than them both being completely self describing but using different names and operations? > > >> That said I don't believe one single source of information is ever likely >> to be (and remain) sufficient for a tool that can be used with multiple >> different brokers (there will always be 'extensible' elements, such as the >> queue-declare 'arguments' for which you will need to consult some other >> source of documentation). >> > Perhaps, though I'd argue that it's just a recursive type - so you supply > a Map parameter and describe the properties of the Map and their types. > Ultimately to be of use this stuff has to be described *somewhere*, making > said documentation *structured* doesn't then seem unreasonable. > > I'm probably on a losing streak with this, but at least you guys know > where I'm coming from now, if there are better approaches to document this > and better ways to make sure that said documentation does in fact happen > then I'll go with the flow. Having said all the above I'm not in any way against having a mechanism to serve up the schema through AMQP... I just think it should only ever be a last resort and is really an indication that we have not done things well if tools are going to need to resort to this in order to manage AMQP entities. I think the vast majority of management should be able to be covered by simple CRUD operations. Those that aren't I would really like to see us standardise as much as possible. If anything for meta-data I might suggest an optional DESCRIBE / HELP operation that takes a parameter of the operation name that you want the meta data of, and then brings back a map of name->(type,description) or something. > > >> Neither am I in any way advocating for or against schema retrieval >> mechanisms. >> >> I do think a generic tool for in some way 'managing' - e.g. like >> qpid-config add|del|list or a gui equivalent - a range of different >> brokers, each with divergent but overlapping sets of semantics, is both >> feasible and (potentially) useful. I'd be interested to hear other opinions >> on that though, especially with regard to usefulness. >> > I'd agree that it's a difficult one. My gut feeling is that with the right > sort of schema (and perhaps by "right" this includes annotations) then at > the very least it will be a whole lot easier to write more general tooling. > It's not black and white by any means - for example I look at > management-schema.xml and look at the QMF GUI and I've made "judgement > calls" on some of the properties that just take up real estate and those > which are useful and TBH I have "coded" pages for specific Node types, but > I do often wonder if I could make things more general. > > Perhaps the differences between the C++ and Java Brokers gives us a chance > to figure out if it's actually possible to do useful "generic" tooling. > Perhaps rather than sweating blood trying to align the Management Nodes and > Manageable Entities we try to use a consistent way to (structured) document > them and see if that allows us to provide common tooling at least for Qpid > whilst still celebrating their differences. If we can't do it for Qpid then > there's no hope more widely, but if we can then at least we've got an > approach. > I'm very keen on this. I would like to tease out the capabilities that we have in common... and those that we don't... and work out which are useful generic concepts and which are bespoke and implementation dependent. > > At the very least it's good to be having this discussion and getting some > of the different perspectives on the table - even if I'm losing the > argument at the moment :-D > > All discussion is good :-) -- Rob > Frase > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
