You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@syncope.apache.org by Sergey Beryozkin <sb...@gmail.com> on 2015/01/23 13:12:51 UTC
Minor Syncope WADL issue
Hi All
Colm found out few weeks back that a Syncope REST service WADL can not
be generated back into the Java code with a CXF wadl-to-java plugin.
Here is the original info Colm helped with:
A ResourceService has two "list" methods:
@GET
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
List<ResourceTO> list();
@GET
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
List<ResourceTO> list(@NotNull @MatrixParam("connectorId") Long
connInstanceId);
This is represented in WADL like this: (I've removed <doc> and some
other mark up. like extra representations, etc):
<resource path="/resources">
<param name="connectorId" style="matrix" type="xs:long"/>
<method name="GET">
<response>
<representation mediaType="application/xml"
element="syncope1:resources"/>
</response>
</method>
<method name="GET">
<response>
<representation mediaType="application/xml"
element="syncope1:resources"/>
</response>
</method>
</resource>
here is a relevant generated Java code:
@GET
@Produces({"application/xml", "application/json" })
Resources list(@MatrixParam("connectorId") Long connectorId);
@GET
@Produces({"application/xml", "application/json" })
Resources list(@MatrixParam("connectorId") Long connectorId);
which fails to compile.
The issue stems from the fact the 2 original GET methods depend on a
custom selection algorithm (the optional parameters like MatrixParam) do
not affect the JAX-RS selection algorithm process, hence by default
those 2 methods are equal candidates so an extension is used to make the
selection predictable.
next, WADL requires that the path segment parameters (PathParam or
MatrixParam) are represented as the immediate wadl:resource children as
the generated WADL fragment shows.
Thus a WADL to Java generation has no idea that one of the two list
methods needs to have a MatrixParam in its signature, the other does not.
There are two ways to fix it.
1. simply collapse the original two methods into one and check if
MatrixParam is null inside the method:
@GET
@Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
List<ResourceTO> list(@MatrixParam("connectorId") Long connInstanceId);
The requests with or without this Matrixparam will be routed to
this method. The only side-effect: the client proxies which do list()
would need to do list(null).
2. I've added a new WADLGenerator property in CXF 3.0.3,
"ignoreOverloadedMethods". If it is set then you'd just get:
<resource path="/resources">
<param name="connectorId" style="matrix" type="xs:long"/>
<method name="GET">
<response>
<representation mediaType="application/xml"
element="syncope1:resources"/>
</response>
</method>
</resource>
which is correct. We can tune the generator further to have
<param name="connectorId" style="matrix" type="xs:long" required="false"/>
but matrix parameters are optional by the definition.
Finally, not an issue but a praise for a WADL stylesheet shipped with
Syncope. I saw a recent presentation from Colm, and I thought, wow,
would it be great if CXF WADLGenerator could optionally reference such a
stylesheet via an XML processing instruction. In fact I've even updated
the generator to do it if it is configured with a reference to
a class path resource.
We've done in CXF some work for the optional Swagger integration and
Andriy Redko even did a demo. I think one of the reasons Swagger is so
popular because people can get UI auto-generated out of it.
Would it possible to get this style-sheet shipped in a self-contained
module? CXF users who need would add it to a classpath and then
configure CXF WADLGenerator with a class path reference to it...
Cheers, Sergey
Re: Minor Syncope WADL issue
Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi,
On 06/02/15 15:57, Francesco Chicchiriccò wrote:
> On 06/02/2015 14:38, Sergey Beryozkin wrote:
>> On 06/02/15 13:01, Francesco Chicchiriccò wrote:
>>> On 05/02/2015 12:29, Sergey Beryozkin wrote:
>>>> Hi Francesco
>>>> On 05/02/15 08:13, Francesco Chicchiriccò wrote:
>>>>> On 04/02/2015 14:49, Sergey Beryozkin wrote:
>>>>>> Hi Francesco,
>>>>>>
>>>>>>>>> Finally, not an issue but a praise for a WADL stylesheet shipped
>>>>>>>>> with
>>>>>>>>> Syncope. I saw a recent presentation from Colm, and I thought,
>>>>>>>>> wow,
>>>>>>>>> would it be great if CXF WADLGenerator could optionally reference
>>>>>>>>> such
>>>>>>>>> a stylesheet via an XML processing instruction. In fact I've even
>>>>>>>>> updated the generator to do it if it is configured with a
>>>>>>>>> reference to
>>>>>>>>> a class path resource.
>>>>>>>>> We've done in CXF some work for the optional Swagger
>>>>>>>>> integration and
>>>>>>>>> Andriy Redko even did a demo. I think one of the reasons Swagger
>>>>>>>>> is so
>>>>>>>>> popular because people can get UI auto-generated out of it.
>>>>>>>>>
>>>>>>>>> Would it possible to get this style-sheet shipped in a
>>>>>>>>> self-contained
>>>>>>>>> module? CXF users who need would add it to a classpath and then
>>>>>>>>> configure CXF WADLGenerator with a class path reference to it...
>>>>>>>>
>>>>>>>> Nice that you like our old-fashioned-technology XSLT :-)
>>>>>>>> When I built that I've also taken a look at Swagger, liked it but
>>>>>>>> had to
>>>>>>>> drop it out because of some heavy dependency (the Scala compiler).
>>>>>>>>
>>>>>>> I think WADL is very capable. I think Swagger is flying because
>>>>>>> it is
>>>>>>> uses a JSON format (it is just more popular as opposed to more
>>>>>>> capable
>>>>>>> than XML), has the option to add the extensions, and + UI.
>>>>>>> WADL is more capable in describing REST services IMHO, the
>>>>>>> extensions
>>>>>>> can be easily added, UI can be there. I'm not trying to say people
>>>>>>> have
>>>>>>> to use WADL if they like Swagger :-), but WADL does deserve a bit
>>>>>>> more
>>>>>>> 'justice' I'd say, it was a very well designed spec from M.Hadley
>>>>>>>
>>>>>>>> If you want, and also provide some details and guidance about
>>>>>>>> how to
>>>>>>>> fit
>>>>>>>> into there, I can contribute the XSL to a new CXF module and we can
>>>>>>>> have
>>>>>>>> also Syncope to depend on that. WDYT?
>>>>>>>>
>>>>>>> I'll try to create a CXF test with some basic copy/transform
>>>>>>> template
>>>>>>> and then I'll share a link and we can discuss what might be done
>>>>>>> next
>>>>>>
>>>>>> I prototyped some initial code where CXF WADLGenerator can be
>>>>>> asked to
>>>>>> either add a processing instruction to a WADL DOM response or
>>>>>> transform it locally ([1], [2]).
>>>>>
>>>>> I've seen your commits: the idea is to experiment with 3.0.4-SNAPSHOT,
>>>>> right? (that would ease testing against Syncope, in case).
>>>>>
>>>> Yes or may be even 3.0.5-SNAPSHOT. Right now WADLGenerator can be
>>>> linked to stylesheets in general which can help people to do minor
>>>> WADL transformations or experiment with the one available at [3]...
>>>>>> So the idea is that a developer would update WADLGenerator with a
>>>>>> template reference, and then the local or browser based
>>>>>> transformation
>>>>>> will happen.
>>>>>>
>>>>>> A template like the one at [3] is easy enough to use as it has no
>>>>>> extra parameters.
>>>>>> I've checked Syncope WADL templates, they are a bit more involved
>>>>>> with
>>>>>> JQuery being used, etc, no wonder the result is so impressive :-)
>>>>>>
>>>>>> I'm not sure if it really makes sense to try and do a browser-based
>>>>>> transformation with Syncope templates, the local one might do.
>>>>>
>>>>> Agree: think that the transformation we currently do in Syncope [4]
>>>>> is a
>>>>> Servlet depending on Cocoon 3.0 (which is not strictly necessary, in
>>>>> this case).
>>>>> Basically, the same WADL file is processed twice: for generating
>>>>> index.html (via index.xsl) and for generating schema_X_Y.html (via
>>>>> index.xsl) - where X is the position of the schema in the WADL file
>>>>> and
>>>>> Y is the schema prefix.
>>>>> With index.xsl links are generated to address references in the
>>>>> related
>>>>> schema page.
>>>>>
>>>>> This second aspect is particularly hard to implement with simple
>>>>> browser-based transformation.
>>>>>
>>>> OK, I understand
>>>>
>>>>>> I'd like to experiment with the index.xsl first. It depends on JQuery
>>>>>> libraries being available at the web server. I think it is
>>>>>> reasonable,
>>>>>> just a minor query here, can JQuery optionally tried first at CDN
>>>>>> first and if it is a local network only then do try a local web
>>>>>> server ?
>>>>>
>>>>> I'd say that we should give the opportunity to specify:
>>>>>
>>>>> * a local CSS (currently index.xsl embeds something very basic)
>>>>> * CDN or local references to jQuery / HighlightJS
>>>>>
>>>> Sure
>>>>>> The other question is what is the relationship between index.xsl and
>>>>>> schema.xsl. Can index.html import schema.xsl in principle ? Can using
>>>>>> index.xsl only would turn WADL to HTML ?
>>>>>
>>>>> As explained above, index.xsl generates links to HTML pages that are
>>>>> supposed to be generated via schema.xsl; this can be turned off,
>>>>> naturally, but would result in a significant feature drop, to me.
>>>> Sure.
>>>>
>>>> What is your opinion on index.xsl importing schema.xsl, with index.xsl
>>>> delegating to schema.xsl targets when it matches a grammar, passing it
>>>> the required parameters ? It is been awhile since I did some
>>>> moderately complex XSLT but I vaguely recall it may be possible to do
>>>> it in XSLT. If it were possible to do a single transformation only via
>>>> this refactoring then WADLGenerator would most likely be able to work
>>>> with index.html too.
>>>
>>> Importing schema.xsl into index.xsl (or simply merging the two into a
>>> single XSLT, which is equivalent) can be done.
>>>
>>> The point is that, at least for the current page design and linking, we
>>> need to have (at least) two separate HTML files: index.html and
>>> schema_X_Y.html; and for this reason two separate XSLT files are
>>> required.
>>>
>>> Refactoring things so that a single HTML page is used for both operation
>>> description and schema information is indeed possible, but I don't think
>>> it is trivial - at least for me.
>>>
>> I'm definitely not proposing to change anything with respect to the
>> current page design - it is perfect. What I've been trying to explore
>> is whether it is possible to have import.xsl importing schema.xsl,
>> while still having multiple out documents produced. Apparently XSLT
>> 2.0 makes it easy and I guess something similar, possibly Xalan
>> specific, is available for XSLT 1.0.
>>
>> However, having said all of it - I've finally ended up looking at
>> WADLServlet, sorry, should've done it earlier. I was under the
>> impression that the schema HTML files were generated at the same time
>> as index.html and where stored to the temp storage.
>>
>> My fault, sorry for waisting your time,
>>
>>>>>> I guess it makes sense to see if this model (configuring CXF
>>>>>> WADLGenerator with a reference to Syncope index.xsl only) works -
>>>>>> either with a local or in-browser transform.
>>>>>
>>>>> Agree: how are you thinking to organize such PoC? Do you want me to
>>>>> contribute / review something in particular? Is there any issue at
>>>>> CXF for this?
>>>> I've no particular plan yet. I guess it all depends on whether Syncope
>>>> WADLServlet would stay as a prerequisite for 3rd party users or not.
>>>>
>>>> If index.xsl importing schema.xsl can work then it would likely make
>>>> sense to have a standalone module for keeping these stylesheets plus
>>>> extra resources like CSS files, etc. (Syncope sub-project or module or
>>>> the same in CXF but it is you who did it all so IMHO it should be in
>>>> the Syncope space, but it can be discussed).
>>>>
>>>> Otherwise it would likely make sense to have WADLServlet + the
>>>> stylesheets be in a standalone module...
>>>>
>>>> Whichever way it is done Syncope would still use WADLServlet, nno real
>>>> side-effects. CXF (and other) users would either work directly with
>>>> two stylesheets or indirectly via WADLServlet...
>>>>
>>>> Something like that. Can you please give me a favor and check if
>>>> index/schema xsl import idea works and then we can review what can be
>>>> done next ?
>>>
>>> As said above, the whole point is if we are able to have all the current
>>> features in a single HTML page: if so, producing a single XSLT is surely
>>> possible (by merging current index.xsl and schema.xsl); unfortunately, I
>>> don't see this change as trivial.
>>>
>>> Alternatively, we can disable the schema linking from operations: in
>>> this case only a modified index.xsl is needed.
>>>
>> I'm not proposing anything changed at all in the actual HTML production.
>> Unfortunately I got confused and as such I don't think it is realistic
>> to link Syncope stylesheets with CXF WADLGenerator.
>>
>> I'd have no problems recommending users just to get a Syncope core on
>> the classpath if they'd like to try the stylesheets (and may be a
>> WADLServlet - if it can also run as a filter so that it can be
>> interposed on top of CXFServlet, etc). I'm not sure if WADLServlet +
>> stylesheets need to be in a dedicated module. Up to the Syncope team.
>
> No need to be sorry at all :-)
>
> About moving WADLServlet + stylesheets to a separate module, this is
> certainly possible: for the moment one could include 'core' with
> 'classes' classifier to get everything, but we might consider putting
> such resources in a separate module as part of the ongoing refactoring
> [5] for SYNCOPE-620.
>
> Can you provide a simple snippet of how things should go if one wants to
> have Syncope's WADL presentation in a 3rd party CXF-based project?
if WADLServlet were able to run not only as a servlet but also as a
filter then I guess the following should work:
<web-app>
<filer>
<filter-name>WADLServlet</servlet-name>
<filter-class>
org.apache.syncope.core.rest.WADLServlet
</filter-class>
</filter>
<servlet>
<servlet-name>CXFServlet</servlet-name>
<servlet-class>
org.apache.cxf.transport.servlet.CXFServlet
</servlet-class>
</servlet>
</web-app>
That should do.
Also as I mentioned I'd be fine with pointing users to Syncope and
telling them, give it a try, just get the syncope core on the classpath,
it would also raise the awareness about Syncope in general :-). May be
you can postpone considering moving it out to a diff module until users
start asking :-) given that it may present some challenges.
I'd also like to clarify that it is not a problem at all that Syncope
stylesheets would not possible to link directly with CXF WADLGenerator;
the generator can 'set up' the simple transformations and this would be
useful on its own (example, users may want to update a bit WADL XML or
convert XML to JSON, etc). Syncope WADL presentation is at a much higher
level and as such does require a more sophisticated support...
Thanks, Sergey
>
>>>
>>>>>> [1] http://git-wip-us.apache.org/repos/asf/cxf/commit/28379a02
>>>>>> [2] http://git-wip-us.apache.org/repos/asf/cxf/commit/ad8e4ddf
>>>>>> [3]
>>>>>> https://github.com/ipcsystems/wadl-stylesheet/blob/master/wadl.xsl
>>>>> [4]
>>>>> https://github.com/apache/syncope/blob/1_2_X/core/src/main/java/org/apache/syncope/core/rest/WADLServlet.java
>>>>>
> [5]
> https://git1-us-west.apache.org/repos/asf?p=syncope.git;a=tree;f=syncope620;hb=refs/heads/2_0_X
>
>
Re: Minor Syncope WADL issue
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 06/02/2015 14:38, Sergey Beryozkin wrote:
> On 06/02/15 13:01, Francesco Chicchiriccò wrote:
>> On 05/02/2015 12:29, Sergey Beryozkin wrote:
>>> Hi Francesco
>>> On 05/02/15 08:13, Francesco Chicchiriccò wrote:
>>>> On 04/02/2015 14:49, Sergey Beryozkin wrote:
>>>>> Hi Francesco,
>>>>>
>>>>>>>> Finally, not an issue but a praise for a WADL stylesheet shipped
>>>>>>>> with
>>>>>>>> Syncope. I saw a recent presentation from Colm, and I thought,
>>>>>>>> wow,
>>>>>>>> would it be great if CXF WADLGenerator could optionally reference
>>>>>>>> such
>>>>>>>> a stylesheet via an XML processing instruction. In fact I've even
>>>>>>>> updated the generator to do it if it is configured with a
>>>>>>>> reference to
>>>>>>>> a class path resource.
>>>>>>>> We've done in CXF some work for the optional Swagger
>>>>>>>> integration and
>>>>>>>> Andriy Redko even did a demo. I think one of the reasons Swagger
>>>>>>>> is so
>>>>>>>> popular because people can get UI auto-generated out of it.
>>>>>>>>
>>>>>>>> Would it possible to get this style-sheet shipped in a
>>>>>>>> self-contained
>>>>>>>> module? CXF users who need would add it to a classpath and then
>>>>>>>> configure CXF WADLGenerator with a class path reference to it...
>>>>>>>
>>>>>>> Nice that you like our old-fashioned-technology XSLT :-)
>>>>>>> When I built that I've also taken a look at Swagger, liked it but
>>>>>>> had to
>>>>>>> drop it out because of some heavy dependency (the Scala compiler).
>>>>>>>
>>>>>> I think WADL is very capable. I think Swagger is flying because
>>>>>> it is
>>>>>> uses a JSON format (it is just more popular as opposed to more
>>>>>> capable
>>>>>> than XML), has the option to add the extensions, and + UI.
>>>>>> WADL is more capable in describing REST services IMHO, the
>>>>>> extensions
>>>>>> can be easily added, UI can be there. I'm not trying to say people
>>>>>> have
>>>>>> to use WADL if they like Swagger :-), but WADL does deserve a bit
>>>>>> more
>>>>>> 'justice' I'd say, it was a very well designed spec from M.Hadley
>>>>>>
>>>>>>> If you want, and also provide some details and guidance about
>>>>>>> how to
>>>>>>> fit
>>>>>>> into there, I can contribute the XSL to a new CXF module and we can
>>>>>>> have
>>>>>>> also Syncope to depend on that. WDYT?
>>>>>>>
>>>>>> I'll try to create a CXF test with some basic copy/transform
>>>>>> template
>>>>>> and then I'll share a link and we can discuss what might be done
>>>>>> next
>>>>>
>>>>> I prototyped some initial code where CXF WADLGenerator can be
>>>>> asked to
>>>>> either add a processing instruction to a WADL DOM response or
>>>>> transform it locally ([1], [2]).
>>>>
>>>> I've seen your commits: the idea is to experiment with 3.0.4-SNAPSHOT,
>>>> right? (that would ease testing against Syncope, in case).
>>>>
>>> Yes or may be even 3.0.5-SNAPSHOT. Right now WADLGenerator can be
>>> linked to stylesheets in general which can help people to do minor
>>> WADL transformations or experiment with the one available at [3]...
>>>>> So the idea is that a developer would update WADLGenerator with a
>>>>> template reference, and then the local or browser based
>>>>> transformation
>>>>> will happen.
>>>>>
>>>>> A template like the one at [3] is easy enough to use as it has no
>>>>> extra parameters.
>>>>> I've checked Syncope WADL templates, they are a bit more involved
>>>>> with
>>>>> JQuery being used, etc, no wonder the result is so impressive :-)
>>>>>
>>>>> I'm not sure if it really makes sense to try and do a browser-based
>>>>> transformation with Syncope templates, the local one might do.
>>>>
>>>> Agree: think that the transformation we currently do in Syncope [4]
>>>> is a
>>>> Servlet depending on Cocoon 3.0 (which is not strictly necessary, in
>>>> this case).
>>>> Basically, the same WADL file is processed twice: for generating
>>>> index.html (via index.xsl) and for generating schema_X_Y.html (via
>>>> index.xsl) - where X is the position of the schema in the WADL file
>>>> and
>>>> Y is the schema prefix.
>>>> With index.xsl links are generated to address references in the
>>>> related
>>>> schema page.
>>>>
>>>> This second aspect is particularly hard to implement with simple
>>>> browser-based transformation.
>>>>
>>> OK, I understand
>>>
>>>>> I'd like to experiment with the index.xsl first. It depends on JQuery
>>>>> libraries being available at the web server. I think it is
>>>>> reasonable,
>>>>> just a minor query here, can JQuery optionally tried first at CDN
>>>>> first and if it is a local network only then do try a local web
>>>>> server ?
>>>>
>>>> I'd say that we should give the opportunity to specify:
>>>>
>>>> * a local CSS (currently index.xsl embeds something very basic)
>>>> * CDN or local references to jQuery / HighlightJS
>>>>
>>> Sure
>>>>> The other question is what is the relationship between index.xsl and
>>>>> schema.xsl. Can index.html import schema.xsl in principle ? Can using
>>>>> index.xsl only would turn WADL to HTML ?
>>>>
>>>> As explained above, index.xsl generates links to HTML pages that are
>>>> supposed to be generated via schema.xsl; this can be turned off,
>>>> naturally, but would result in a significant feature drop, to me.
>>> Sure.
>>>
>>> What is your opinion on index.xsl importing schema.xsl, with index.xsl
>>> delegating to schema.xsl targets when it matches a grammar, passing it
>>> the required parameters ? It is been awhile since I did some
>>> moderately complex XSLT but I vaguely recall it may be possible to do
>>> it in XSLT. If it were possible to do a single transformation only via
>>> this refactoring then WADLGenerator would most likely be able to work
>>> with index.html too.
>>
>> Importing schema.xsl into index.xsl (or simply merging the two into a
>> single XSLT, which is equivalent) can be done.
>>
>> The point is that, at least for the current page design and linking, we
>> need to have (at least) two separate HTML files: index.html and
>> schema_X_Y.html; and for this reason two separate XSLT files are
>> required.
>>
>> Refactoring things so that a single HTML page is used for both operation
>> description and schema information is indeed possible, but I don't think
>> it is trivial - at least for me.
>>
> I'm definitely not proposing to change anything with respect to the
> current page design - it is perfect. What I've been trying to explore
> is whether it is possible to have import.xsl importing schema.xsl,
> while still having multiple out documents produced. Apparently XSLT
> 2.0 makes it easy and I guess something similar, possibly Xalan
> specific, is available for XSLT 1.0.
>
> However, having said all of it - I've finally ended up looking at
> WADLServlet, sorry, should've done it earlier. I was under the
> impression that the schema HTML files were generated at the same time
> as index.html and where stored to the temp storage.
>
> My fault, sorry for waisting your time,
>
>>>>> I guess it makes sense to see if this model (configuring CXF
>>>>> WADLGenerator with a reference to Syncope index.xsl only) works -
>>>>> either with a local or in-browser transform.
>>>>
>>>> Agree: how are you thinking to organize such PoC? Do you want me to
>>>> contribute / review something in particular? Is there any issue at
>>>> CXF for this?
>>> I've no particular plan yet. I guess it all depends on whether Syncope
>>> WADLServlet would stay as a prerequisite for 3rd party users or not.
>>>
>>> If index.xsl importing schema.xsl can work then it would likely make
>>> sense to have a standalone module for keeping these stylesheets plus
>>> extra resources like CSS files, etc. (Syncope sub-project or module or
>>> the same in CXF but it is you who did it all so IMHO it should be in
>>> the Syncope space, but it can be discussed).
>>>
>>> Otherwise it would likely make sense to have WADLServlet + the
>>> stylesheets be in a standalone module...
>>>
>>> Whichever way it is done Syncope would still use WADLServlet, nno real
>>> side-effects. CXF (and other) users would either work directly with
>>> two stylesheets or indirectly via WADLServlet...
>>>
>>> Something like that. Can you please give me a favor and check if
>>> index/schema xsl import idea works and then we can review what can be
>>> done next ?
>>
>> As said above, the whole point is if we are able to have all the current
>> features in a single HTML page: if so, producing a single XSLT is surely
>> possible (by merging current index.xsl and schema.xsl); unfortunately, I
>> don't see this change as trivial.
>>
>> Alternatively, we can disable the schema linking from operations: in
>> this case only a modified index.xsl is needed.
>>
> I'm not proposing anything changed at all in the actual HTML production.
> Unfortunately I got confused and as such I don't think it is realistic
> to link Syncope stylesheets with CXF WADLGenerator.
>
> I'd have no problems recommending users just to get a Syncope core on
> the classpath if they'd like to try the stylesheets (and may be a
> WADLServlet - if it can also run as a filter so that it can be
> interposed on top of CXFServlet, etc). I'm not sure if WADLServlet +
> stylesheets need to be in a dedicated module. Up to the Syncope team.
No need to be sorry at all :-)
About moving WADLServlet + stylesheets to a separate module, this is
certainly possible: for the moment one could include 'core' with
'classes' classifier to get everything, but we might consider putting
such resources in a separate module as part of the ongoing refactoring
[5] for SYNCOPE-620.
Can you provide a simple snippet of how things should go if one wants to
have Syncope's WADL presentation in a 3rd party CXF-based project?
>>
>>>>> [1] http://git-wip-us.apache.org/repos/asf/cxf/commit/28379a02
>>>>> [2] http://git-wip-us.apache.org/repos/asf/cxf/commit/ad8e4ddf
>>>>> [3]
>>>>> https://github.com/ipcsystems/wadl-stylesheet/blob/master/wadl.xsl
>>>> [4]
>>>> https://github.com/apache/syncope/blob/1_2_X/core/src/main/java/org/apache/syncope/core/rest/WADLServlet.java
>>>>
[5]
https://git1-us-west.apache.org/repos/asf?p=syncope.git;a=tree;f=syncope620;hb=refs/heads/2_0_X
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/
Re: Minor Syncope WADL issue
Posted by Sergey Beryozkin <sb...@gmail.com>.
On 06/02/15 13:01, Francesco Chicchiriccò wrote:
> On 05/02/2015 12:29, Sergey Beryozkin wrote:
>> Hi Francesco
>> On 05/02/15 08:13, Francesco Chicchiriccò wrote:
>>> On 04/02/2015 14:49, Sergey Beryozkin wrote:
>>>> Hi Francesco,
>>>>
>>>>>>> Finally, not an issue but a praise for a WADL stylesheet shipped
>>>>>>> with
>>>>>>> Syncope. I saw a recent presentation from Colm, and I thought, wow,
>>>>>>> would it be great if CXF WADLGenerator could optionally reference
>>>>>>> such
>>>>>>> a stylesheet via an XML processing instruction. In fact I've even
>>>>>>> updated the generator to do it if it is configured with a
>>>>>>> reference to
>>>>>>> a class path resource.
>>>>>>> We've done in CXF some work for the optional Swagger integration and
>>>>>>> Andriy Redko even did a demo. I think one of the reasons Swagger
>>>>>>> is so
>>>>>>> popular because people can get UI auto-generated out of it.
>>>>>>>
>>>>>>> Would it possible to get this style-sheet shipped in a
>>>>>>> self-contained
>>>>>>> module? CXF users who need would add it to a classpath and then
>>>>>>> configure CXF WADLGenerator with a class path reference to it...
>>>>>>
>>>>>> Nice that you like our old-fashioned-technology XSLT :-)
>>>>>> When I built that I've also taken a look at Swagger, liked it but
>>>>>> had to
>>>>>> drop it out because of some heavy dependency (the Scala compiler).
>>>>>>
>>>>> I think WADL is very capable. I think Swagger is flying because it is
>>>>> uses a JSON format (it is just more popular as opposed to more capable
>>>>> than XML), has the option to add the extensions, and + UI.
>>>>> WADL is more capable in describing REST services IMHO, the extensions
>>>>> can be easily added, UI can be there. I'm not trying to say people
>>>>> have
>>>>> to use WADL if they like Swagger :-), but WADL does deserve a bit more
>>>>> 'justice' I'd say, it was a very well designed spec from M.Hadley
>>>>>
>>>>>> If you want, and also provide some details and guidance about how to
>>>>>> fit
>>>>>> into there, I can contribute the XSL to a new CXF module and we can
>>>>>> have
>>>>>> also Syncope to depend on that. WDYT?
>>>>>>
>>>>> I'll try to create a CXF test with some basic copy/transform template
>>>>> and then I'll share a link and we can discuss what might be done next
>>>>
>>>> I prototyped some initial code where CXF WADLGenerator can be asked to
>>>> either add a processing instruction to a WADL DOM response or
>>>> transform it locally ([1], [2]).
>>>
>>> I've seen your commits: the idea is to experiment with 3.0.4-SNAPSHOT,
>>> right? (that would ease testing against Syncope, in case).
>>>
>> Yes or may be even 3.0.5-SNAPSHOT. Right now WADLGenerator can be
>> linked to stylesheets in general which can help people to do minor
>> WADL transformations or experiment with the one available at [3]...
>>>> So the idea is that a developer would update WADLGenerator with a
>>>> template reference, and then the local or browser based transformation
>>>> will happen.
>>>>
>>>> A template like the one at [3] is easy enough to use as it has no
>>>> extra parameters.
>>>> I've checked Syncope WADL templates, they are a bit more involved with
>>>> JQuery being used, etc, no wonder the result is so impressive :-)
>>>>
>>>> I'm not sure if it really makes sense to try and do a browser-based
>>>> transformation with Syncope templates, the local one might do.
>>>
>>> Agree: think that the transformation we currently do in Syncope [4] is a
>>> Servlet depending on Cocoon 3.0 (which is not strictly necessary, in
>>> this case).
>>> Basically, the same WADL file is processed twice: for generating
>>> index.html (via index.xsl) and for generating schema_X_Y.html (via
>>> index.xsl) - where X is the position of the schema in the WADL file and
>>> Y is the schema prefix.
>>> With index.xsl links are generated to address references in the related
>>> schema page.
>>>
>>> This second aspect is particularly hard to implement with simple
>>> browser-based transformation.
>>>
>> OK, I understand
>>
>>>> I'd like to experiment with the index.xsl first. It depends on JQuery
>>>> libraries being available at the web server. I think it is reasonable,
>>>> just a minor query here, can JQuery optionally tried first at CDN
>>>> first and if it is a local network only then do try a local web
>>>> server ?
>>>
>>> I'd say that we should give the opportunity to specify:
>>>
>>> * a local CSS (currently index.xsl embeds something very basic)
>>> * CDN or local references to jQuery / HighlightJS
>>>
>> Sure
>>>> The other question is what is the relationship between index.xsl and
>>>> schema.xsl. Can index.html import schema.xsl in principle ? Can using
>>>> index.xsl only would turn WADL to HTML ?
>>>
>>> As explained above, index.xsl generates links to HTML pages that are
>>> supposed to be generated via schema.xsl; this can be turned off,
>>> naturally, but would result in a significant feature drop, to me.
>> Sure.
>>
>> What is your opinion on index.xsl importing schema.xsl, with index.xsl
>> delegating to schema.xsl targets when it matches a grammar, passing it
>> the required parameters ? It is been awhile since I did some
>> moderately complex XSLT but I vaguely recall it may be possible to do
>> it in XSLT. If it were possible to do a single transformation only via
>> this refactoring then WADLGenerator would most likely be able to work
>> with index.html too.
>
> Importing schema.xsl into index.xsl (or simply merging the two into a
> single XSLT, which is equivalent) can be done.
>
> The point is that, at least for the current page design and linking, we
> need to have (at least) two separate HTML files: index.html and
> schema_X_Y.html; and for this reason two separate XSLT files are required.
>
> Refactoring things so that a single HTML page is used for both operation
> description and schema information is indeed possible, but I don't think
> it is trivial - at least for me.
>
I'm definitely not proposing to change anything with respect to the
current page design - it is perfect. What I've been trying to explore is
whether it is possible to have import.xsl importing schema.xsl, while
still having multiple out documents produced. Apparently XSLT 2.0 makes
it easy and I guess something similar, possibly Xalan specific, is
available for XSLT 1.0.
However, having said all of it - I've finally ended up looking at
WADLServlet, sorry, should've done it earlier. I was under the
impression that the schema HTML files were generated at the same time as
index.html and where stored to the temp storage.
My fault, sorry for waisting your time,
>>>> I guess it makes sense to see if this model (configuring CXF
>>>> WADLGenerator with a reference to Syncope index.xsl only) works -
>>>> either with a local or in-browser transform.
>>>
>>> Agree: how are you thinking to organize such PoC? Do you want me to
>>> contribute / review something in particular? Is there any issue at
>>> CXF for this?
>> I've no particular plan yet. I guess it all depends on whether Syncope
>> WADLServlet would stay as a prerequisite for 3rd party users or not.
>>
>> If index.xsl importing schema.xsl can work then it would likely make
>> sense to have a standalone module for keeping these stylesheets plus
>> extra resources like CSS files, etc. (Syncope sub-project or module or
>> the same in CXF but it is you who did it all so IMHO it should be in
>> the Syncope space, but it can be discussed).
>>
>> Otherwise it would likely make sense to have WADLServlet + the
>> stylesheets be in a standalone module...
>>
>> Whichever way it is done Syncope would still use WADLServlet, nno real
>> side-effects. CXF (and other) users would either work directly with
>> two stylesheets or indirectly via WADLServlet...
>>
>> Something like that. Can you please give me a favor and check if
>> index/schema xsl import idea works and then we can review what can be
>> done next ?
>
> As said above, the whole point is if we are able to have all the current
> features in a single HTML page: if so, producing a single XSLT is surely
> possible (by merging current index.xsl and schema.xsl); unfortunately, I
> don't see this change as trivial.
>
> Alternatively, we can disable the schema linking from operations: in
> this case only a modified index.xsl is needed.
>
I'm not proposing anything changed at all in the actual HTML production.
Unfortunately I got confused and as such I don't think it is realistic
to link Syncope stylesheets with CXF WADLGenerator.
I'd have no problems recommending users just to get a Syncope core on
the classpath if they'd like to try the stylesheets (and may be a
WADLServlet - if it can also run as a filter so that it can be
interposed on top of CXFServlet, etc). I'm not sure if WADLServlet +
stylesheets need to be in a dedicated module. Up to the Syncope team
Sorry I got confused
Cheers
Sergey
> Regards.
>
>>>> [1] http://git-wip-us.apache.org/repos/asf/cxf/commit/28379a02
>>>> [2] http://git-wip-us.apache.org/repos/asf/cxf/commit/ad8e4ddf
>>>> [3] https://github.com/ipcsystems/wadl-stylesheet/blob/master/wadl.xsl
>>> [4]
>>> https://github.com/apache/syncope/blob/1_2_X/core/src/main/java/org/apache/syncope/core/rest/WADLServlet.java
>>>
>
Re: Minor Syncope WADL issue
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 05/02/2015 12:29, Sergey Beryozkin wrote:
> Hi Francesco
> On 05/02/15 08:13, Francesco Chicchiriccò wrote:
>> On 04/02/2015 14:49, Sergey Beryozkin wrote:
>>> Hi Francesco,
>>>
>>>>>> Finally, not an issue but a praise for a WADL stylesheet shipped
>>>>>> with
>>>>>> Syncope. I saw a recent presentation from Colm, and I thought, wow,
>>>>>> would it be great if CXF WADLGenerator could optionally reference
>>>>>> such
>>>>>> a stylesheet via an XML processing instruction. In fact I've even
>>>>>> updated the generator to do it if it is configured with a
>>>>>> reference to
>>>>>> a class path resource.
>>>>>> We've done in CXF some work for the optional Swagger integration and
>>>>>> Andriy Redko even did a demo. I think one of the reasons Swagger
>>>>>> is so
>>>>>> popular because people can get UI auto-generated out of it.
>>>>>>
>>>>>> Would it possible to get this style-sheet shipped in a
>>>>>> self-contained
>>>>>> module? CXF users who need would add it to a classpath and then
>>>>>> configure CXF WADLGenerator with a class path reference to it...
>>>>>
>>>>> Nice that you like our old-fashioned-technology XSLT :-)
>>>>> When I built that I've also taken a look at Swagger, liked it but
>>>>> had to
>>>>> drop it out because of some heavy dependency (the Scala compiler).
>>>>>
>>>> I think WADL is very capable. I think Swagger is flying because it is
>>>> uses a JSON format (it is just more popular as opposed to more capable
>>>> than XML), has the option to add the extensions, and + UI.
>>>> WADL is more capable in describing REST services IMHO, the extensions
>>>> can be easily added, UI can be there. I'm not trying to say people
>>>> have
>>>> to use WADL if they like Swagger :-), but WADL does deserve a bit more
>>>> 'justice' I'd say, it was a very well designed spec from M.Hadley
>>>>
>>>>> If you want, and also provide some details and guidance about how to
>>>>> fit
>>>>> into there, I can contribute the XSL to a new CXF module and we can
>>>>> have
>>>>> also Syncope to depend on that. WDYT?
>>>>>
>>>> I'll try to create a CXF test with some basic copy/transform template
>>>> and then I'll share a link and we can discuss what might be done next
>>>
>>> I prototyped some initial code where CXF WADLGenerator can be asked to
>>> either add a processing instruction to a WADL DOM response or
>>> transform it locally ([1], [2]).
>>
>> I've seen your commits: the idea is to experiment with 3.0.4-SNAPSHOT,
>> right? (that would ease testing against Syncope, in case).
>>
> Yes or may be even 3.0.5-SNAPSHOT. Right now WADLGenerator can be
> linked to stylesheets in general which can help people to do minor
> WADL transformations or experiment with the one available at [3]...
>>> So the idea is that a developer would update WADLGenerator with a
>>> template reference, and then the local or browser based transformation
>>> will happen.
>>>
>>> A template like the one at [3] is easy enough to use as it has no
>>> extra parameters.
>>> I've checked Syncope WADL templates, they are a bit more involved with
>>> JQuery being used, etc, no wonder the result is so impressive :-)
>>>
>>> I'm not sure if it really makes sense to try and do a browser-based
>>> transformation with Syncope templates, the local one might do.
>>
>> Agree: think that the transformation we currently do in Syncope [4] is a
>> Servlet depending on Cocoon 3.0 (which is not strictly necessary, in
>> this case).
>> Basically, the same WADL file is processed twice: for generating
>> index.html (via index.xsl) and for generating schema_X_Y.html (via
>> index.xsl) - where X is the position of the schema in the WADL file and
>> Y is the schema prefix.
>> With index.xsl links are generated to address references in the related
>> schema page.
>>
>> This second aspect is particularly hard to implement with simple
>> browser-based transformation.
>>
> OK, I understand
>
>>> I'd like to experiment with the index.xsl first. It depends on JQuery
>>> libraries being available at the web server. I think it is reasonable,
>>> just a minor query here, can JQuery optionally tried first at CDN
>>> first and if it is a local network only then do try a local web
>>> server ?
>>
>> I'd say that we should give the opportunity to specify:
>>
>> * a local CSS (currently index.xsl embeds something very basic)
>> * CDN or local references to jQuery / HighlightJS
>>
> Sure
>>> The other question is what is the relationship between index.xsl and
>>> schema.xsl. Can index.html import schema.xsl in principle ? Can using
>>> index.xsl only would turn WADL to HTML ?
>>
>> As explained above, index.xsl generates links to HTML pages that are
>> supposed to be generated via schema.xsl; this can be turned off,
>> naturally, but would result in a significant feature drop, to me.
> Sure.
>
> What is your opinion on index.xsl importing schema.xsl, with index.xsl
> delegating to schema.xsl targets when it matches a grammar, passing it
> the required parameters ? It is been awhile since I did some
> moderately complex XSLT but I vaguely recall it may be possible to do
> it in XSLT. If it were possible to do a single transformation only via
> this refactoring then WADLGenerator would most likely be able to work
> with index.html too.
Importing schema.xsl into index.xsl (or simply merging the two into a
single XSLT, which is equivalent) can be done.
The point is that, at least for the current page design and linking, we
need to have (at least) two separate HTML files: index.html and
schema_X_Y.html; and for this reason two separate XSLT files are required.
Refactoring things so that a single HTML page is used for both operation
description and schema information is indeed possible, but I don't think
it is trivial - at least for me.
>>> I guess it makes sense to see if this model (configuring CXF
>>> WADLGenerator with a reference to Syncope index.xsl only) works -
>>> either with a local or in-browser transform.
>>
>> Agree: how are you thinking to organize such PoC? Do you want me to
>> contribute / review something in particular? Is there any issue at
>> CXF for this?
> I've no particular plan yet. I guess it all depends on whether Syncope
> WADLServlet would stay as a prerequisite for 3rd party users or not.
>
> If index.xsl importing schema.xsl can work then it would likely make
> sense to have a standalone module for keeping these stylesheets plus
> extra resources like CSS files, etc. (Syncope sub-project or module or
> the same in CXF but it is you who did it all so IMHO it should be in
> the Syncope space, but it can be discussed).
>
> Otherwise it would likely make sense to have WADLServlet + the
> stylesheets be in a standalone module...
>
> Whichever way it is done Syncope would still use WADLServlet, nno real
> side-effects. CXF (and other) users would either work directly with
> two stylesheets or indirectly via WADLServlet...
>
> Something like that. Can you please give me a favor and check if
> index/schema xsl import idea works and then we can review what can be
> done next ?
As said above, the whole point is if we are able to have all the current
features in a single HTML page: if so, producing a single XSLT is surely
possible (by merging current index.xsl and schema.xsl); unfortunately, I
don't see this change as trivial.
Alternatively, we can disable the schema linking from operations: in
this case only a modified index.xsl is needed.
Regards.
>>> [1] http://git-wip-us.apache.org/repos/asf/cxf/commit/28379a02
>>> [2] http://git-wip-us.apache.org/repos/asf/cxf/commit/ad8e4ddf
>>> [3] https://github.com/ipcsystems/wadl-stylesheet/blob/master/wadl.xsl
>> [4]
>> https://github.com/apache/syncope/blob/1_2_X/core/src/main/java/org/apache/syncope/core/rest/WADLServlet.java
>>
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/
Re: Minor Syncope WADL issue
Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi Francesco
On 05/02/15 08:13, Francesco Chicchiriccò wrote:
> On 04/02/2015 14:49, Sergey Beryozkin wrote:
>> Hi Francesco,
>>
>>>>> Finally, not an issue but a praise for a WADL stylesheet shipped with
>>>>> Syncope. I saw a recent presentation from Colm, and I thought, wow,
>>>>> would it be great if CXF WADLGenerator could optionally reference such
>>>>> a stylesheet via an XML processing instruction. In fact I've even
>>>>> updated the generator to do it if it is configured with a reference to
>>>>> a class path resource.
>>>>> We've done in CXF some work for the optional Swagger integration and
>>>>> Andriy Redko even did a demo. I think one of the reasons Swagger is so
>>>>> popular because people can get UI auto-generated out of it.
>>>>>
>>>>> Would it possible to get this style-sheet shipped in a self-contained
>>>>> module? CXF users who need would add it to a classpath and then
>>>>> configure CXF WADLGenerator with a class path reference to it...
>>>>
>>>> Nice that you like our old-fashioned-technology XSLT :-)
>>>> When I built that I've also taken a look at Swagger, liked it but
>>>> had to
>>>> drop it out because of some heavy dependency (the Scala compiler).
>>>>
>>> I think WADL is very capable. I think Swagger is flying because it is
>>> uses a JSON format (it is just more popular as opposed to more capable
>>> than XML), has the option to add the extensions, and + UI.
>>> WADL is more capable in describing REST services IMHO, the extensions
>>> can be easily added, UI can be there. I'm not trying to say people have
>>> to use WADL if they like Swagger :-), but WADL does deserve a bit more
>>> 'justice' I'd say, it was a very well designed spec from M.Hadley
>>>
>>>> If you want, and also provide some details and guidance about how to
>>>> fit
>>>> into there, I can contribute the XSL to a new CXF module and we can
>>>> have
>>>> also Syncope to depend on that. WDYT?
>>>>
>>> I'll try to create a CXF test with some basic copy/transform template
>>> and then I'll share a link and we can discuss what might be done next
>>
>> I prototyped some initial code where CXF WADLGenerator can be asked to
>> either add a processing instruction to a WADL DOM response or
>> transform it locally ([1], [2]).
>
> I've seen your commits: the idea is to experiment with 3.0.4-SNAPSHOT,
> right? (that would ease testing against Syncope, in case).
>
Yes or may be even 3.0.5-SNAPSHOT. Right now WADLGenerator can be linked
to stylesheets in general which can help people to do minor WADL
transformations or experiment with the one available at [3]...
>> So the idea is that a developer would update WADLGenerator with a
>> template reference, and then the local or browser based transformation
>> will happen.
>>
>> A template like the one at [3] is easy enough to use as it has no
>> extra parameters.
>> I've checked Syncope WADL templates, they are a bit more involved with
>> JQuery being used, etc, no wonder the result is so impressive :-)
>>
>> I'm not sure if it really makes sense to try and do a browser-based
>> transformation with Syncope templates, the local one might do.
>
> Agree: think that the transformation we currently do in Syncope [4] is a
> Servlet depending on Cocoon 3.0 (which is not strictly necessary, in
> this case).
> Basically, the same WADL file is processed twice: for generating
> index.html (via index.xsl) and for generating schema_X_Y.html (via
> index.xsl) - where X is the position of the schema in the WADL file and
> Y is the schema prefix.
> With index.xsl links are generated to address references in the related
> schema page.
>
> This second aspect is particularly hard to implement with simple
> browser-based transformation.
>
OK, I understand
>> I'd like to experiment with the index.xsl first. It depends on JQuery
>> libraries being available at the web server. I think it is reasonable,
>> just a minor query here, can JQuery optionally tried first at CDN
>> first and if it is a local network only then do try a local web server ?
>
> I'd say that we should give the opportunity to specify:
>
> * a local CSS (currently index.xsl embeds something very basic)
> * CDN or local references to jQuery / HighlightJS
>
Sure
>> The other question is what is the relationship between index.xsl and
>> schema.xsl. Can index.html import schema.xsl in principle ? Can using
>> index.xsl only would turn WADL to HTML ?
>
> As explained above, index.xsl generates links to HTML pages that are
> supposed to be generated via schema.xsl; this can be turned off,
> naturally, but would result in a significant feature drop, to me.
Sure.
What is your opinion on index.xsl importing schema.xsl, with index.xsl
delegating to schema.xsl targets when it matches a grammar, passing it
the required parameters ? It is been awhile since I did some moderately
complex XSLT but I vaguely recall it may be possible to do it in XSLT.
If it were possible to do a single transformation only via this
refactoring then WADLGenerator would most likely be able to work with
index.html too.
>
>> I guess it makes sense to see if this model (configuring CXF
>> WADLGenerator with a reference to Syncope index.xsl only) works -
>> either with a local or in-browser transform.
>
> Agree: how are you thinking to organize such PoC? Do you want me to
> contribute / review something in particular?
> Is there any issue at CXF for this?
>
I've no particular plan yet. I guess it all depends on whether Syncope
WADLServlet would stay as a prerequisite for 3rd party users or not.
If index.xsl importing schema.xsl can work then it would likely make
sense to have a standalone module for keeping these stylesheets plus
extra resources like CSS files, etc. (Syncope sub-project or module or
the same in CXF but it is you who did it all so IMHO it should be in the
Syncope space, but it can be discussed).
Otherwise it would likely make sense to have WADLServlet + the
stylesheets be in a standalone module...
Whichever way it is done Syncope would still use WADLServlet, nno real
side-effects. CXF (and other) users would either work directly with two
stylesheets or indirectly via WADLServlet...
Something like that. Can you please give me a favor and check if
index/schema xsl import idea works and then we can review what can be
done next ?
Many thanks, Sergey
> Regards.
>
>> [1] http://git-wip-us.apache.org/repos/asf/cxf/commit/28379a02
>> [2] http://git-wip-us.apache.org/repos/asf/cxf/commit/ad8e4ddf
>> [3] https://github.com/ipcsystems/wadl-stylesheet/blob/master/wadl.xsl
> [4]
> https://github.com/apache/syncope/blob/1_2_X/core/src/main/java/org/apache/syncope/core/rest/WADLServlet.java
>
>
Re: Minor Syncope WADL issue
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 04/02/2015 14:49, Sergey Beryozkin wrote:
> Hi Francesco,
>
>>>> Finally, not an issue but a praise for a WADL stylesheet shipped with
>>>> Syncope. I saw a recent presentation from Colm, and I thought, wow,
>>>> would it be great if CXF WADLGenerator could optionally reference such
>>>> a stylesheet via an XML processing instruction. In fact I've even
>>>> updated the generator to do it if it is configured with a reference to
>>>> a class path resource.
>>>> We've done in CXF some work for the optional Swagger integration and
>>>> Andriy Redko even did a demo. I think one of the reasons Swagger is so
>>>> popular because people can get UI auto-generated out of it.
>>>>
>>>> Would it possible to get this style-sheet shipped in a self-contained
>>>> module? CXF users who need would add it to a classpath and then
>>>> configure CXF WADLGenerator with a class path reference to it...
>>>
>>> Nice that you like our old-fashioned-technology XSLT :-)
>>> When I built that I've also taken a look at Swagger, liked it but
>>> had to
>>> drop it out because of some heavy dependency (the Scala compiler).
>>>
>> I think WADL is very capable. I think Swagger is flying because it is
>> uses a JSON format (it is just more popular as opposed to more capable
>> than XML), has the option to add the extensions, and + UI.
>> WADL is more capable in describing REST services IMHO, the extensions
>> can be easily added, UI can be there. I'm not trying to say people have
>> to use WADL if they like Swagger :-), but WADL does deserve a bit more
>> 'justice' I'd say, it was a very well designed spec from M.Hadley
>>
>>> If you want, and also provide some details and guidance about how to
>>> fit
>>> into there, I can contribute the XSL to a new CXF module and we can
>>> have
>>> also Syncope to depend on that. WDYT?
>>>
>> I'll try to create a CXF test with some basic copy/transform template
>> and then I'll share a link and we can discuss what might be done next
>
> I prototyped some initial code where CXF WADLGenerator can be asked to
> either add a processing instruction to a WADL DOM response or
> transform it locally ([1], [2]).
I've seen your commits: the idea is to experiment with 3.0.4-SNAPSHOT,
right? (that would ease testing against Syncope, in case).
> So the idea is that a developer would update WADLGenerator with a
> template reference, and then the local or browser based transformation
> will happen.
>
> A template like the one at [3] is easy enough to use as it has no
> extra parameters.
> I've checked Syncope WADL templates, they are a bit more involved with
> JQuery being used, etc, no wonder the result is so impressive :-)
>
> I'm not sure if it really makes sense to try and do a browser-based
> transformation with Syncope templates, the local one might do.
Agree: think that the transformation we currently do in Syncope [4] is a
Servlet depending on Cocoon 3.0 (which is not strictly necessary, in
this case).
Basically, the same WADL file is processed twice: for generating
index.html (via index.xsl) and for generating schema_X_Y.html (via
index.xsl) - where X is the position of the schema in the WADL file and
Y is the schema prefix.
With index.xsl links are generated to address references in the related
schema page.
This second aspect is particularly hard to implement with simple
browser-based transformation.
> I'd like to experiment with the index.xsl first. It depends on JQuery
> libraries being available at the web server. I think it is reasonable,
> just a minor query here, can JQuery optionally tried first at CDN
> first and if it is a local network only then do try a local web server ?
I'd say that we should give the opportunity to specify:
* a local CSS (currently index.xsl embeds something very basic)
* CDN or local references to jQuery / HighlightJS
> The other question is what is the relationship between index.xsl and
> schema.xsl. Can index.html import schema.xsl in principle ? Can using
> index.xsl only would turn WADL to HTML ?
As explained above, index.xsl generates links to HTML pages that are
supposed to be generated via schema.xsl; this can be turned off,
naturally, but would result in a significant feature drop, to me.
> I guess it makes sense to see if this model (configuring CXF
> WADLGenerator with a reference to Syncope index.xsl only) works -
> either with a local or in-browser transform.
Agree: how are you thinking to organize such PoC? Do you want me to
contribute / review something in particular?
Is there any issue at CXF for this?
Regards.
> [1] http://git-wip-us.apache.org/repos/asf/cxf/commit/28379a02
> [2] http://git-wip-us.apache.org/repos/asf/cxf/commit/ad8e4ddf
> [3] https://github.com/ipcsystems/wadl-stylesheet/blob/master/wadl.xsl
[4]
https://github.com/apache/syncope/blob/1_2_X/core/src/main/java/org/apache/syncope/core/rest/WADLServlet.java
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/
Re: Minor Syncope WADL issue
Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi Francesco,
>>> Finally, not an issue but a praise for a WADL stylesheet shipped with
>>> Syncope. I saw a recent presentation from Colm, and I thought, wow,
>>> would it be great if CXF WADLGenerator could optionally reference such
>>> a stylesheet via an XML processing instruction. In fact I've even
>>> updated the generator to do it if it is configured with a reference to
>>> a class path resource.
>>> We've done in CXF some work for the optional Swagger integration and
>>> Andriy Redko even did a demo. I think one of the reasons Swagger is so
>>> popular because people can get UI auto-generated out of it.
>>>
>>> Would it possible to get this style-sheet shipped in a self-contained
>>> module? CXF users who need would add it to a classpath and then
>>> configure CXF WADLGenerator with a class path reference to it...
>>
>> Nice that you like our old-fashioned-technology XSLT :-)
>> When I built that I've also taken a look at Swagger, liked it but had to
>> drop it out because of some heavy dependency (the Scala compiler).
>>
> I think WADL is very capable. I think Swagger is flying because it is
> uses a JSON format (it is just more popular as opposed to more capable
> than XML), has the option to add the extensions, and + UI.
> WADL is more capable in describing REST services IMHO, the extensions
> can be easily added, UI can be there. I'm not trying to say people have
> to use WADL if they like Swagger :-), but WADL does deserve a bit more
> 'justice' I'd say, it was a very well designed spec from M.Hadley
>
>> If you want, and also provide some details and guidance about how to fit
>> into there, I can contribute the XSL to a new CXF module and we can have
>> also Syncope to depend on that. WDYT?
>>
> I'll try to create a CXF test with some basic copy/transform template
> and then I'll share a link and we can discuss what might be done next
I prototyped some initial code where CXF WADLGenerator can be asked to
either add a processing instruction to a WADL DOM response or transform
it locally ([1], [2]).
So the idea is that a developer would update WADLGenerator with a
template reference, and then the local or browser based transformation
will happen.
A template like the one at [3] is easy enough to use as it has no extra
parameters.
I've checked Syncope WADL templates, they are a bit more involved with
JQuery being used, etc, no wonder the result is so impressive :-)
I'm not sure if it really makes sense to try and do a browser-based
transformation with Syncope templates, the local one might do.
I'd like to experiment with the index.xsl first. It depends on JQuery
libraries being available at the web server. I think it is reasonable,
just a minor query here, can JQuery optionally tried first at CDN first
and if it is a local network only then do try a local web server ?
The other question is what is the relationship between index.xsl and
schema.xsl. Can index.html import schema.xsl in principle ? Can using
index.xsl only would turn WADL to HTML ?
I guess it makes sense to see if this model (configuring CXF
WADLGenerator with a reference to Syncope index.xsl only) works - either
with a local or in-browser transform.
Thanks, Sergey
[1] http://git-wip-us.apache.org/repos/asf/cxf/commit/28379a02
[2] http://git-wip-us.apache.org/repos/asf/cxf/commit/ad8e4ddf
[3] https://github.com/ipcsystems/wadl-stylesheet/blob/master/wadl.xsl
Re: Minor Syncope WADL issue
Posted by Sergey Beryozkin <sb...@gmail.com>.
Hi Francesco,
On 23/01/15 14:56, Francesco Chicchiriccò wrote:
> On 23/01/2015 13:12, Sergey Beryozkin wrote:
>> Hi All
>>
>> Colm found out few weeks back that a Syncope REST service WADL can not
>> be generated back into the Java code with a CXF wadl-to-java plugin.
>> Here is the original info Colm helped with:
>>
>> A ResourceService has two "list" methods:
>>
>> @GET
>> @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
>> List<ResourceTO> list();
>>
>> @GET
>> @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
>> List<ResourceTO> list(@NotNull @MatrixParam("connectorId") Long
>> connInstanceId);
>>
>> This is represented in WADL like this: (I've removed <doc> and some
>> other mark up. like extra representations, etc):
>>
>> <resource path="/resources">
>> <param name="connectorId" style="matrix" type="xs:long"/>
>> <method name="GET">
>> <response>
>> <representation mediaType="application/xml"
>> element="syncope1:resources"/>
>> </response>
>> </method>
>> <method name="GET">
>> <response>
>> <representation mediaType="application/xml"
>> element="syncope1:resources"/>
>> </response>
>> </method>
>> </resource>
>>
>> here is a relevant generated Java code:
>>
>> @GET
>> @Produces({"application/xml", "application/json" })
>> Resources list(@MatrixParam("connectorId") Long connectorId);
>>
>> @GET
>> @Produces({"application/xml", "application/json" })
>> Resources list(@MatrixParam("connectorId") Long connectorId);
>>
>> which fails to compile.
>>
>>
>> The issue stems from the fact the 2 original GET methods depend on a
>> custom selection algorithm (the optional parameters like MatrixParam)
>> do not affect the JAX-RS selection algorithm process, hence by default
>> those 2 methods are equal candidates so an extension is used to make
>> the selection predictable.
>>
>> next, WADL requires that the path segment parameters (PathParam or
>> MatrixParam) are represented as the immediate wadl:resource children
>> as the generated WADL fragment shows.
>>
>> Thus a WADL to Java generation has no idea that one of the two list
>> methods needs to have a MatrixParam in its signature, the other does not.
>>
>> There are two ways to fix it.
>>
>> 1. simply collapse the original two methods into one and check if
>> MatrixParam is null inside the method:
>>
>> @GET
>> @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
>> List<ResourceTO> list(@MatrixParam("connectorId") Long
>> connInstanceId);
>>
>>
>> The requests with or without this Matrixparam will be routed to
>> this method. The only side-effect: the client proxies which do list()
>> would need to do list(null).
>>
>> 2. I've added a new WADLGenerator property in CXF 3.0.3,
>> "ignoreOverloadedMethods". If it is set then you'd just get:
>>
>> <resource path="/resources">
>> <param name="connectorId" style="matrix" type="xs:long"/>
>> <method name="GET">
>> <response>
>> <representation mediaType="application/xml"
>> element="syncope1:resources"/>
>> </response>
>> </method>
>> </resource>
>>
>> which is correct. We can tune the generator further to have
>> <param name="connectorId" style="matrix" type="xs:long"
>> required="false"/>
>>
>> but matrix parameters are optional by the definition.
>
> Hi Sergey,
> I am not sure I am following everything above, but are you suggesting
> that adding ignoreOverloadedMethods="true" (since Syncope is using CXF
> 3.0.3) would solve the issue?
>
Yes, this is one of the options
> In any case, would you mind to open an issue on JIRA for this? Thanks.
>
Sure.
>> Finally, not an issue but a praise for a WADL stylesheet shipped with
>> Syncope. I saw a recent presentation from Colm, and I thought, wow,
>> would it be great if CXF WADLGenerator could optionally reference such
>> a stylesheet via an XML processing instruction. In fact I've even
>> updated the generator to do it if it is configured with a reference to
>> a class path resource.
>> We've done in CXF some work for the optional Swagger integration and
>> Andriy Redko even did a demo. I think one of the reasons Swagger is so
>> popular because people can get UI auto-generated out of it.
>>
>> Would it possible to get this style-sheet shipped in a self-contained
>> module? CXF users who need would add it to a classpath and then
>> configure CXF WADLGenerator with a class path reference to it...
>
> Nice that you like our old-fashioned-technology XSLT :-)
> When I built that I've also taken a look at Swagger, liked it but had to
> drop it out because of some heavy dependency (the Scala compiler).
>
I think WADL is very capable. I think Swagger is flying because it is
uses a JSON format (it is just more popular as opposed to more capable
than XML), has the option to add the extensions, and + UI.
WADL is more capable in describing REST services IMHO, the extensions
can be easily added, UI can be there. I'm not trying to say people have
to use WADL if they like Swagger :-), but WADL does deserve a bit more
'justice' I'd say, it was a very well designed spec from M.Hadley
> If you want, and also provide some details and guidance about how to fit
> into there, I can contribute the XSL to a new CXF module and we can have
> also Syncope to depend on that. WDYT?
>
I'll try to create a CXF test with some basic copy/transform template
and then I'll share a link and we can discuss what might be done next
Thanks, Sergey
> Regards.
>
--
Sergey Beryozkin
Talend Community Coders
http://coders.talend.com/
Blog: http://sberyozkin.blogspot.com
Re: Minor Syncope WADL issue
Posted by Francesco Chicchiriccò <il...@apache.org>.
On 23/01/2015 13:12, Sergey Beryozkin wrote:
> Hi All
>
> Colm found out few weeks back that a Syncope REST service WADL can not
> be generated back into the Java code with a CXF wadl-to-java plugin.
> Here is the original info Colm helped with:
>
> A ResourceService has two "list" methods:
>
> @GET
> @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
> List<ResourceTO> list();
>
> @GET
> @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
> List<ResourceTO> list(@NotNull @MatrixParam("connectorId") Long
> connInstanceId);
>
> This is represented in WADL like this: (I've removed <doc> and some
> other mark up. like extra representations, etc):
>
> <resource path="/resources">
> <param name="connectorId" style="matrix" type="xs:long"/>
> <method name="GET">
> <response>
> <representation mediaType="application/xml"
> element="syncope1:resources"/>
> </response>
> </method>
> <method name="GET">
> <response>
> <representation mediaType="application/xml"
> element="syncope1:resources"/>
> </response>
> </method>
> </resource>
>
> here is a relevant generated Java code:
>
> @GET
> @Produces({"application/xml", "application/json" })
> Resources list(@MatrixParam("connectorId") Long connectorId);
>
> @GET
> @Produces({"application/xml", "application/json" })
> Resources list(@MatrixParam("connectorId") Long connectorId);
>
> which fails to compile.
>
>
> The issue stems from the fact the 2 original GET methods depend on a
> custom selection algorithm (the optional parameters like MatrixParam)
> do not affect the JAX-RS selection algorithm process, hence by default
> those 2 methods are equal candidates so an extension is used to make
> the selection predictable.
>
> next, WADL requires that the path segment parameters (PathParam or
> MatrixParam) are represented as the immediate wadl:resource children
> as the generated WADL fragment shows.
>
> Thus a WADL to Java generation has no idea that one of the two list
> methods needs to have a MatrixParam in its signature, the other does not.
>
> There are two ways to fix it.
>
> 1. simply collapse the original two methods into one and check if
> MatrixParam is null inside the method:
>
> @GET
> @Produces({ MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON })
> List<ResourceTO> list(@MatrixParam("connectorId") Long
> connInstanceId);
>
>
> The requests with or without this Matrixparam will be routed to
> this method. The only side-effect: the client proxies which do list()
> would need to do list(null).
>
> 2. I've added a new WADLGenerator property in CXF 3.0.3,
> "ignoreOverloadedMethods". If it is set then you'd just get:
>
> <resource path="/resources">
> <param name="connectorId" style="matrix" type="xs:long"/>
> <method name="GET">
> <response>
> <representation mediaType="application/xml"
> element="syncope1:resources"/>
> </response>
> </method>
> </resource>
>
> which is correct. We can tune the generator further to have
> <param name="connectorId" style="matrix" type="xs:long"
> required="false"/>
>
> but matrix parameters are optional by the definition.
Hi Sergey,
I am not sure I am following everything above, but are you suggesting
that adding ignoreOverloadedMethods="true" (since Syncope is using CXF
3.0.3) would solve the issue?
In any case, would you mind to open an issue on JIRA for this? Thanks.
> Finally, not an issue but a praise for a WADL stylesheet shipped with
> Syncope. I saw a recent presentation from Colm, and I thought, wow,
> would it be great if CXF WADLGenerator could optionally reference such
> a stylesheet via an XML processing instruction. In fact I've even
> updated the generator to do it if it is configured with a reference to
> a class path resource.
> We've done in CXF some work for the optional Swagger integration and
> Andriy Redko even did a demo. I think one of the reasons Swagger is so
> popular because people can get UI auto-generated out of it.
>
> Would it possible to get this style-sheet shipped in a self-contained
> module? CXF users who need would add it to a classpath and then
> configure CXF WADLGenerator with a class path reference to it...
Nice that you like our old-fashioned-technology XSLT :-)
When I built that I've also taken a look at Swagger, liked it but had to
drop it out because of some heavy dependency (the Scala compiler).
If you want, and also provide some details and guidance about how to fit
into there, I can contribute the XSL to a new CXF module and we can have
also Syncope to depend on that. WDYT?
Regards.
--
Francesco Chicchiriccò
Tirasa - Open Source Excellence
http://www.tirasa.net/
Involved at The Apache Software Foundation:
member, Syncope PMC chair, Cocoon PMC, Olingo PMC
http://people.apache.org/~ilgrosso/