On 23/01/13 10:16, Jan Bernhardt wrote:
-----Original Message-----
From: Sergey Beryozkin [mailto:sberyoz...@gmail.com]
Sent: Mittwoch, 23. Januar 2013 10:52
To: dev@syncope.apache.org
Subject: Re: [DISCUSS] New REST Service Interfaces - ConfigurationService
Hi Jan
On 23/01/13 08:06, Jan Bernhardt wrote:
Hi Syncoper,
here are the proposed changes for our Configuration Service:
* Changing Create response type to javax.ws.rs.core.Response. This way
we can set response HTTP Status code (201 created) without requiring
HttpServletResponse as method parameter. Also according to best RESTful
practices instead of returning newly created object directly, only URL for new
Object (Configuration) will be returned. Console does not even care about
created response, thus network traffic can be reduced, by not sending
object (configuration). If consumer does care about new object he can easily
follow provided URL (in response) and retrieve new object.
I think it is fine echoing back the created resource representation (alongside
Location) when it can help the client to avoid the extra round trip, I guess it
depends on the actual requirements of the console client
I would think that for roles and users it would be best to directly responding
created objects since they contain propagation information.
For all other resources our console does not even care about, so there is no
need to directly respond them.
If other "consoles" do care, they can follow the provided URL or call interface
read operation with provided ID (from response header).
* Changed ModelAndView response type to Set<ValidatorTO> /
Set<MailTemplateTO> and introduced wrapper TO classes for ValidatorTO
and MailTemplateTO.
One thing I should mention is that auto-describing the explicit collections is
tricky in WADL, though of course one can register a custom WADL document
with CXF; personally I prefer using collection wrapper beans - it is simpler to
get them described and also easier to attach some more metadata to such
collection in the form of the wrapper properties, that said, returning the
explicit collections will also work
Interesting point. Thanks for this feedback Sergey. I currently do not see any need for
additional metadata, so I would rather want to avoid additional refactoring work, even
thou I think using a "WrapperClass" would be a better interface design.
Do you expect this WADL generation problem to remain for a long time? I would
rather not want to change my interface design due to a temporal missing feature
of another component...
I did not say there was a definite problem :-) but it can be tricky;
when we have an explicit collection we kind of lose control over how the
wrapper element may look like - the runtime tries its best to deduce the
most suitable wrapper name - and this name can also be configured to
make it predictable.
The more complex problem is to do with the fact that the actual schema
(wadl:grammar) does not have a schema element describing such a
syntesized wrapper generated by JAXB - so the generator tries to modify
the generated schema block manually - we have a test for List of JAXB
beans - I guess that should work for Sets too - most likely yes - would
be a trivial fix if not - but this custom schema modification has not
been extensively tested so there could be some issues there, nnot 100% sure
But as I said, a custom WADL document can also be registered if the
default auto-generated one won't offer the perfect description
Cheers, Sergey
Best regards.
Jan
Cheers, Sergey
* Changed return type from update() and delete() to void, since console
does not even care about it, and I think this should be best practice anyway,
since consumer knows updates object already and does not care about
deleted ones, therefore there is no need to send them over the network.
Any objections?
Best regards.
Jan
-----Original Message-----
From: Jan Bernhardt [mailto:jbernha...@talend.com]
Sent: Donnerstag, 17. Januar 2013 14:04
To: dev@syncope.apache.org
Subject: RE: [Discussion] New REST Service Interfaces - Entitlements
Hi Syncoper,
The following changes are proposed regarding AuthenticationController:
=== Renaming Service ===
Rename AuthenticationController to EntitlementService(Impl), since
containing methods have little to nothing to do with authentication.
It is only about Entitlements...
=== Changing response Type ===
listEntitlements() returns a List<String> whereas getEntitlements()
returns a Set<String>.
From my point of view both methods should return a SET since
entitlements have no order and cannot exists or be assigned more than
once.
Due to some JAX-B / JAX-RS limitations, it is not possible to return
a collection with primitive data types in java. A wrapper class is required,
e.g.
Set<EntitlementTO>.
EntitlementTO can be modeled in one of two ways:
Option 1:
<EntitlementTOs>
<EntitlementTO>ROLE_ADMIN</EntitlementTO>
<EntitlementTO>ROLE_SUPERUSER</EntitlementTO>
</EntitlementTOs>
Option 2:
<EntitlementTOs>
<EntitlementTO>
<name>ROLE_ADMIN</name>
</EntitlementTO>
<EntitlementTO>
<name> ROLE_SUPERUSER</name>
</EntitlementTO>
</EntitlementTOs>
Option 1 matches more or less current marshaling. I personally would
prefer Option 2 because this would give us the opportunity to easily
extend EntitlementTO at a later point (if needed) without becoming
incompatible with previous version.
WDYT?
All of these changes will not apply to current Spring
Controller/Services, but only future CXF REST Service. So
AuthenticationController will not be renamed now, and responsetype of
AuthenticationController will not change. Changes only apply for new
Service Interface and (Proxy) Implementation.
Best regards.
Jan
