Hi Jun, GSOC coding started on the 23rd of may, so you need to focus on coding your GSoC project now. If you're not done with this I suggest you to put it on hold and start working on XEclipse restification.
There may be some sinergies with the Android Client project so we'll need to communicate a lot on this mailing list. Could you please send a working plan for this week (almost gone) and the next one? Thanks, Fabio P.S. : I am currently on a parental leave till the end of the next week but I am planning to read mail quite often. On Tue, May 24, 2011 at 4:56 PM, Jun Han <[email protected]> wrote: > Hi, Fabio, > > Thanks a lot for detailed reply. > > I agree with you that the approach of defining a MessageBodyWriter to > produce html is more modularized and easier to maintain the code > compared with adding another method of producing html for all of the > xwiki resource classes. > > In the previous email, I proposed something similar to JAXBProvder and > JSONProvider in restlet: > @Provider > @Produces("text/html") > class HTMLProvider extends AbstractProvider > > In restlet api, AbstractProvider implements MessageBodyWriter and > MessageBodyReader. Regarding the implementation, I thought of using XML > transformation at the beginning as I did not know there is a mothod of > document.getRenderedContent(), which can produce HTML content. > > When I look more into the source code, I think one possible way to > re-factor the REST API would be to enhance XWikiResource class and its > inherited classess instead of adding more code to the auto generated > JAXB classes. In the current PageResource implementation, more methods > in getRenderedContent() may be provided so that different media type can > be supported. > > @GET > public PageResource getPage() { > return the getRenderedContent() > } > > implement getRenderedContent() with the following methods > getRenderedContent(MediaType) > |-- getRenderContentXML > |-- getRenderContentHTML > |-- getRenderContentPDF > > > Bridge pattern or adapter pattern may be applied in this case, which can > separate the implementation of ContentProvider and actual XWikiResource > itself. > > Thomas also pointed out the Android client project also needs to use > REST API. I prefer re-factoring it as soon as possible, if REST API > needs further re-factoring in the future anyway. > > Best regards > > Jun Han > > On Thu, May 19, 2011 at 6:22 AM, Fabio Mancinelli > <[email protected]> wrote: >> On Thu, May 19, 2011 at 7:53 AM, Jun Han <[email protected]> wrote: >>> Hi Fabio, >>> >>> Thanks a lot for your clarification. >>> >>> Following RootResource class, I created a class called PageHTMLResource, >>> which extends XWikiResource. This class defines a new endpoint >>> (/wikis/{wikiName}/spaces/{spaceName}/pagesHTML/{pageName}) and produces >>> "text/html" content. >>> >>> This link shows the class implementation as well as curl request and >>> server response. >>> https://docs.google.com/document/d/18xfQBSBxXT31a_QY5uBQ7c5MTbt9UEvk6zXO9F32iqk/edit?hl=en&authkey=CID73rEJ >>> I hope I understand the requirement this time. >>> >>> I was also trying to use the same end point as PageResource class. >>> However, it does not work as the restlet complains "WARNING: There is >>> already a root resource class with path >>> /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName}". >>> Therefore, adding a new end point seems like the way to go. >>> >>> If this is case, how many resources are needed to provide HTML content? >>> page, space, links, etc.? >>> Another question would be how to design the new end points? >>> For now, "HTML" is appended after "pages" for PageHTMLResource, which >>> gives /wikis/{wikiName}/spaces/{spaceName}/pagesHTML/{pageName}. >>> This is just a quick and dirty design. >>> Do you have better ideas? >>> >> Well, I think this solution is not good because if we want to add more >> media types (e.g., PDF, etc.) we should introduce a lot of URIs. >> Instead we can leverage the current ones and use HTTP metadata to >> produce the right output. >> >> To do this we have 2 ways: >> >> 1) Either we define a MessageBodyWriter >> (http://jsr311.java.net/nonav/javadoc/javax/ws/rs/ext/MessageBodyWriter.html) >> that @Produces("text/html") for an org.xwiki.rest.model.jaxb.Page >> object that is returned by PageResource.getPage() (i.e., the method >> that is called when GET is called on the >> /wikis/{wikiName}/spaces/{spaceName}/pages/{pageName} URI) >> >> 2) Or we enhance the PageResource class by providing a new method, >> e.g., getPageHTML that @Produces("text/html") and returns a String >> which is the actual rendered content. >> >> @Produces is the annotation that enables content negotiation. If a >> client requests a specific media type, the @Produces is used by the >> framework to locate the entity that should provide the response. >> >> The first option is better wrt modularity but it has a problem. The >> org.xwiki.rest.model.jaxb.Page doesn't have any link to the original >> XWiki Document from where it has been built, so we cannot directly >> call getRenderedContent. A quick solution would be to re-get the >> associated XWiki Document based on the information present in the >> org.xwiki.rest.model.jaxb.Page object and call getRenderedContent(). A >> bit ugly because this makes the work done in the getPage() method >> useless. >> >> The second option is straightforward, works fine and doesn't have the >> drawbacks of the first but introduces a second way for adding media >> format support. I mean this is perfectly legal in JAX-RS, it's just >> that from an architectural point of view, it is nice to have media >> type support using body writers because they are XWiki components and >> they can be injected in the system without touching existing code >> (giving more flexibility and better extensibility) >> >> So how do we proceed? >> >> To do 1) I think we should refactor a the whole system in order to >> make original XWiki entities to be accessible from JAXB objects. Since >> we are using a JAXB compiler to automatically generate these classes >> from an XSD schema, I am not sure that we can tell the compiler to >> "add an Object entity field to the generated classes" (have to check >> if). If this is possible then we're done, otherwise we might need to >> stop using the compiler and write explicitly the classes using JAXB >> annotations for serializing only the relevant fields. >> >> 2) as I said is straightforward. >> >> Since my idea was to give you some insights about how the REST API >> works, I think you can implement 2) because 1) is too much (though, if >> you feel comfortable you might try :)). This mail and your >> implementation should provide you enough background to understand how >> things work under the hood in case we'll need to patch some things >> server side while working on XEclipse. >> >> So try to go for 2). You can also have a look at the JAX-RS >> specification that details all the concepts I've mentioned before and >> that we use in the RESTful API backend. >> >> Thanks, >> Fabio >> >> >> >> >>> Best regards >>> Jun Han >>> >>> On 05/18/2011 08:23 AM, Fabio Mancinelli wrote: >>>> Hi Jun >>>> >>>> On Wed, May 18, 2011 at 5:49 AM, Jun Han<[email protected]> wrote: >>>>> Hi Fabio and Thomas, >>>>> >>>>> Thanks a lot. >>>>> >>>>> I took some time to look at how to produce XML output in Xwiki REST API. >>>>> >>>>> The job of marshaling Java object to XML is done by >>>>> restlet.ext.JAXBProvider via Restlet 1.1.10. >>>>> |@Provider >>>>> @Consumes("application/xml") >>>>> @Produces("application/xml") >>>>> class JAXBProvider extends AbstractProvider| >>>>> >>>>> Similarly, our HTMLProvider can also be devised if we want to provide a >>>>> HTML output. >>>>> |@Provider >>>>> @Produces("text/html") >>>>> class HTMLProvider extends AbstractProvider| >>>>> >>>>> As discussed earlier, another issue is about html page's format and >>>>> content. >>>>> An easy way would be to transform XML to html page via XSLT. >>>>> I also checked the current version of Restlet (2.0.7 stable). They added >>>>> Representation class in v2.0 and plan to add Representation >>>>> transformation (i.e., XML -> HTML) in version v2.2 via XSLT. see >>>>> http://wiki.restlet.org/developers/175-restlet.html >>>>> Therefore, I think XSLT approach might work for plain html. >>>>> >>>>> Take a simple page as an example, >>>>> >>>>> |<?xml version="1.0" encoding="UTF-8" standalone="yes"?> >>>>> <page xmlns="http://www.xwiki.org";> >>>>> <title>New title</title> >>>>> <content>New content</content> >>>>> </page>| >>>>> >>>>> What would be the output of html page? >>>>> >>>>> |<html> >>>>> <H1>Page<H1> >>>>> <p>namespace: http://www.xwiki.org</p> >>>>> <p>title: New title</p> >>>>> <p>content: New content</p> >>>>> </html> >>>>> | >>>>> Best regards >>>>> Jun Han >>>>> >>>> I think you misunderstood what is the purpose of this functionality... >>>> We don't want to render in HTML the XML produced by the standard REST >>>> response. We simply want to return the HTML that comes from the >>>> rendering of the page content. >>>> >>>> Basically, in its simplest form, this boils down to write a resource >>>> that returns what is generated by Document.getRenderedContent() >>>> >>>> As a side note keep in mind that we are using JAX-RS in top of >>>> Restlet, so when defining a resource you need to create a @Component >>>> Class that extends XWikiResource and also list it in the >>>> META-INF/components.txt >>>> >>>> You can have a look at >>>> https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rest/xwiki-platform-rest-server/src/main/java/org/xwiki/rest/resources/RootResource.java >>>> and >>>> https://github.com/xwiki/xwiki-platform/blob/master/xwiki-platform-core/xwiki-platform-rest/xwiki-platform-rest-server/src/main/resources/META-INF/components.txt >>>> to see what I am talking about. >>>> >>>> Thanks, >>>> Fabio >>>> >>>> >>>> >>>>> On 5/17/2011 5:29 AM, Fabio Mancinelli wrote: >>>>>> Hi Jun >>>>>> >>>>>> On Tue, May 17, 2011 at 9:16 AM, Jun Han<[email protected]> wrote: >>>>>>> Dear all, >>>>>>> >>>>>>> Regarding REST API for XWiki, >>>>>>> Source codes are in >>>>>>> xwiki-trunk/xwiki-platform/xwiki-platform-core/xwiki-platform-rest. >>>>>>> Test codes are in >>>>>>> xwiki-trunk/xwiki-enterprise/xwiki-enterprise-test/xwiki-enterprise-test-rest. >>>>>>> I hope I am looking at the correct places. >>>>>>> >>>>>> Correct. >>>>>> >>>>>>> XWiki-5820 is related to adding an endpoint for providing a rendered >>>>>>> version of the page. >>>>>>> Does REST API need to invoke xwiki-rendering library in order to render >>>>>>> the html content? >>>>>>> >>>>>> There are several getRenderedContent() methods in the Document >>>>>> class... It should be enough to call them. >>>>>> >>>>>>> The current implementation will return various resources, (e.g., pages, >>>>>>> tags, attachments), and produce XML responses in most cases. >>>>>>> In XWiki-5820, only page resources will be rendered, right? >>>>>>> >>>>>>> A straight-forward way may be to add additional end point (getPage and >>>>>>> getPageInHTML), and they will be invoked according to different Accept >>>>>>> http headers. >>>>>>> >>>>>>> It would be great that an example can be given to show the expected >>>>>>> input and output. >>>>>>> >>>>>> Actually this is a good question... >>>>>> >>>>>> The original purpose of this resource was to provide a rendered >>>>>> version of a page (typically in HTML). >>>>>> Now, provided that we render in HTML, how this HTML should be returned? >>>>>> >>>>>> If we render with the complete skin we would end up with the same >>>>>> content already available from http://.../xwiki/bin/view/Space/Page >>>>>> So the idea was to return the "bare HTML" that could be emdedded in >>>>>> other contexts. >>>>>> >>>>>> For the input we can consider Accept headers and media parameters >>>>>> (already handled by the backend) >>>>>> >>>>>> Thanks, >>>>>> Fabio >>>>>> >>>>>>> Best regards >>>>>>> Jun Han >>>>>>> _______________________________________________ >>>>>>> devs mailing list >>>>>>> [email protected] >>>>>>> http://lists.xwiki.org/mailman/listinfo/devs >>>>>>> >>>>>> _______________________________________________ >>>>>> devs mailing list >>>>>> [email protected] >>>>>> http://lists.xwiki.org/mailman/listinfo/devs >>>>> _______________________________________________ >>>>> devs mailing list >>>>> [email protected] >>>>> http://lists.xwiki.org/mailman/listinfo/devs >>>>> >>>> _______________________________________________ >>>> devs mailing list >>>> [email protected] >>>> http://lists.xwiki.org/mailman/listinfo/devs >>> >>> _______________________________________________ >>> devs mailing list >>> [email protected] >>> http://lists.xwiki.org/mailman/listinfo/devs >>> >> _______________________________________________ >> devs mailing list >> [email protected] >> http://lists.xwiki.org/mailman/listinfo/devs >> > > > > -- > Jun Han > Computer Science Department, > the University of Georgia > http://sites.google.com/site/junhan37/ > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
