You are viewing a plain text version of this content. The canonical link for it is here.
Posted to photark-dev@incubator.apache.org by Adriano Crestani <ad...@gmail.com> on 2010/11/14 05:26:39 UTC
Low level API
Hi,
Currently, every Photark component (jcr, security, search) exposes its
functionalities as SOA services, so they can be easily wired together. I
think at high level it's working well. However, at low level it's being very
painful to introduce new features, since practically every implementation is
coded directly in the service interface, making it very hardcoded.
Right now, we can see it happening when we try to add a new kind of remote
album, which requires to change the gallery implementation and add a new
condition block to handle each different type of photo provider. That's why
I'm trying to identify each of these components and define common APIs to
them.
At the same time, I'm trying to introduce a tagging system that should, at
least at low level, replace the album system. Just to clarify, the main
difference between tag and album is that photos are not contained in a tag,
as it's contained in an album, instead, photos are contained directly in the
gallery and they may have many tags. This means the same photo may be at the
same time in the album "travel" and " favorite moments", I mean, it may be
tagged by "travel" and "favorite moments". Using this tagging system at low
level, we can still create an application that uses the old album concept,
the application only needs to limit the number of tags applied to a photo to
1 and say "album" instead of "tag" :)
The interfaces below are only for use at low level. How their functionality
will be exposed is up to the services (high level) API. Please, comments and
suggestions about them are welcome :)
/**
* <p>
* This interface should be implemented by every gallery implementation. It
* provides methods to manipulate images' info and tags.
* </p>
*
* <p>
* The implementation is responsible to store the information about every
tag
* and image added to the gallery, and optionally its raw data.
* </p>
*/
public interface Gallery {
/**
* Add image to the gallery. Only the information about the image, for raw
* data, use {@link #uploadImage(byte[], String)}
*
* @return an image object containing the new image ID
*/
Image addImage(Image image) throws PhotarkException;
/**
* Update an image information.
*/
void updateImage(Image image) throws PhotarkException;
/**
* Update an image if it was previously aded using
* {@link #uploadImage(byte[], String)}
*/
void updateImageData(Image image, byte[] data) throws PhotarkException;
/**
* Remove an image from the gallery
*/
void removeImage(String imageID) throws PhotarkException;
/**
* Upload a raw image data to the gallery. It works as
* {@link #addImage(Image)}, but it also stores the raw image data for later
* use.
*/
Image uploadImage(byte[] data, String name) throws PhotarkException;
/**
* Add a tag to an image. If the tag does not exist in the gallery it's
* automatically created.
*/
void addTagToImage(String tagName, String imageID) throws PhotarkException;
/**
* Remove a tag from an image.
*/
void removeTagFromImage(String tagName, String imageID)
throws PhotarkException;
/**
* Update a tag info, adding description and a cover image to it. If the tag
* doesn't exist yet in the gallery, it automatically added, otherwise its
* information is just updated.
*/
void updateTag(Tag tag) throws PhotarkException;
/**
* Remove a tag from the gallery. It's removed from every image its added as
* well as its information (description and cover image).
*/
void removeTag(String tagName) throws PhotarkException;
/**
* Returns all images available in the gallery ordered by its posted date.
*/
List<Image> getImages() throws PhotarkException;
/**
* Returns all images containing the specified tag ordered by its posted
date.
*/
List<Image> getImagesByTag(String tagName) throws PhotarkException;
/**
* Returns all tags available in the gallery.
*/
Set<Tag> getTags() throws PhotarkException;
}
/**
* This interfaces should be implemented by a gallery that supports search
* queries.
*
* @see Gallery
*/
public interface SearchableGallery extends Gallery {
/**
* Returns a query containing all images matching the given search query.
* The returned images are ordered by an arbitrary relevance defined by the
* gallery implementation.
*/
List<Image> search(String query) throws PhotarkException;
}
/**
* <p>
* The implementor of this interface is responsible for register/unregister
* subscriptions to remote photo providers and synchronize the photos
retrieve
* from the remove providers with a gallery.
* </p>
* <p>
* The implementation may use {@link PhotoStreamProvider} interface to
access
* the photo providers. How {@link PhotoStreamProvider}s are
* registered is implementation independent.
* </p>
*/
public interface SubscriptionManager {
/**
* Adds a new subscription.
*
* @return a {@link SubscriptionConfig} object containing the new
* subscription's ID
*/
SubscriptionConfig addSubscription(SubscriptionConfig subscriptionConfig);
/**
* Updates a subscription information, like password, user, etc.
*/
void updateSubscription(SubscriptionConfig subscriptionConfig);
/**
* Removes a subscription
*/
void removeSubscription(String subscriptionID);
/**
* Synchronizes the photos retrieved from the given subscription with the
* gallery.
*/
void syncSubscription(String subscriptionID);
/**
* Returns the {@link Gallery} this {@link SubscriptionManager} synchronizes
* the photos with.
*/
Gallery getGallery();
}
public interface PhotoStreamProvider {
String getProviderType();
List<Image> getImages() throws PhotarkException;
}
Re: Low level API
Posted by Suhothayan Sriskandarajah <su...@gmail.com>.
On 16 November 2010 22:55, Luciano Resende <lu...@gmail.com> wrote:
> On Tue, Nov 16, 2010 at 7:24 AM, Suhothayan Sriskandarajah
> <su...@gmail.com> wrote:
> > On 16 November 2010 20:07, Adriano Crestani <adrianocrestani@gmail.com
> >wrote:
> >
> >> Hi Suhothayan,,
> >>
> >> Yes, my initial idea is to have privacy visibility defined per tag. Do
> you
> >> have any other suggestion?
> >>
> >> great
> >
> > Since there is no JSON RPC calls and we are only dealing with REST, there
> > wont be much implications in implementing security to the rest branch.
> But
> > in order to provide security, each API calls need to be tested against
> the
> > corresponding session cookie, in order to check who calls the request,
> what
> > album is he accessing, and does he has permission to do so, etc...
> >
> > For this to be successful, I Suggest we should come up with Security API
> > which will be published as services, and they will indeed call the low
> level
> > API that we are implementing.
> >
> > Thoughts?
> >
> > Regards
> > Suho
> >
>
> For the REST branch, I'd like to think out of the box and consider
> "applying" security as a quality of service and something that can be
> attached to any API. We have the concept of "SCA Policies" which
> could be used and it would inject an interceptor on each API call that
> would have access to the "request" and it's " headers" and could
> validate the user authorization to a given resource. Having said that,
> we do need the whole Access Control admin APIs (rest services) which
> you created for us in the current trunk code.
>
>
Great,
I'll look in to "SCA Policies"
suho
--
> Luciano Resende
> http://people.apache.org/~lresende <http://people.apache.org/%7Elresende>
> http://twitter.com/lresende1975
> http://lresende.blogspot.com/
>
Re: Low level API
Posted by Luciano Resende <lu...@gmail.com>.
On Tue, Nov 16, 2010 at 7:24 AM, Suhothayan Sriskandarajah
<su...@gmail.com> wrote:
> On 16 November 2010 20:07, Adriano Crestani <ad...@gmail.com>wrote:
>
>> Hi Suhothayan,,
>>
>> Yes, my initial idea is to have privacy visibility defined per tag. Do you
>> have any other suggestion?
>>
>> great
>
> Since there is no JSON RPC calls and we are only dealing with REST, there
> wont be much implications in implementing security to the rest branch. But
> in order to provide security, each API calls need to be tested against the
> corresponding session cookie, in order to check who calls the request, what
> album is he accessing, and does he has permission to do so, etc...
>
> For this to be successful, I Suggest we should come up with Security API
> which will be published as services, and they will indeed call the low level
> API that we are implementing.
>
> Thoughts?
>
> Regards
> Suho
>
For the REST branch, I'd like to think out of the box and consider
"applying" security as a quality of service and something that can be
attached to any API. We have the concept of "SCA Policies" which
could be used and it would inject an interceptor on each API call that
would have access to the "request" and it's " headers" and could
validate the user authorization to a given resource. Having said that,
we do need the whole Access Control admin APIs (rest services) which
you created for us in the current trunk code.
--
Luciano Resende
http://people.apache.org/~lresende
http://twitter.com/lresende1975
http://lresende.blogspot.com/
Re: Low level API
Posted by Adriano Crestani <ad...@gmail.com>.
I'm OK with that.
On Tue, Nov 16, 2010 at 12:24 PM, Suhothayan Sriskandarajah <
suhothayan@gmail.com> wrote:
> On 16 November 2010 20:07, Adriano Crestani <adrianocrestani@gmail.com
> >wrote:
>
> > Hi Suhothayan,,
> >
> > Yes, my initial idea is to have privacy visibility defined per tag. Do
> you
> > have any other suggestion?
> >
> > great
>
> Since there is no JSON RPC calls and we are only dealing with REST, there
> wont be much implications in implementing security to the rest branch. But
> in order to provide security, each API calls need to be tested against the
> corresponding session cookie, in order to check who calls the request, what
> album is he accessing, and does he has permission to do so, etc...
>
> For this to be successful, I Suggest we should come up with Security API
> which will be published as services, and they will indeed call the low
> level
> API that we are implementing.
>
> Thoughts?
>
> Regards
> Suho
>
>
>
> On Tue, Nov 16, 2010 at 11:29 AM, Suhothayan Sriskandarajah <
> > suhothayan@gmail.com> wrote:
> >
> > > On 15 November 2010 00:49, Adriano Crestani <adrianocrestani@gmail.com
> > > >wrote:
> > >
> > > > It would be great to understand the difference between high and low
> > > > level here, particular because I don't think we need a very complex
> > > > and deep API.
> > > >
> > > > High = API exposed as SOA service
> > > > Low = API used by the service implementation to manipulate images and
> > > tags
> > > >
> > > > You mentioned these are low level, then Gallery really seems high
> > > > level. How about PhotoStream ?
> > > >
> > > > Gallery is low level according to the description I just gave above
> :)
> > If
> > > > you want to rename it to PhotoStream, for me it's OK.
> > > >
> > > > I'm not sure about the tag operations. Shouldn't this be like an
> > > > "update" to the image "metadata" where you add a new tag to it ?
> > > >
> > > > That sounds reasonable too :)
> > > >
> > > > I'm not sure I understand this. To me, subscription and the actual
> > > > gallery are decoupled.
> > > >
> > > > The sync operation needs to push the images retrieved from remote
> > > provider
> > > > to a gallery.
> > > >
> > > > Seems good
> > > +1
> > >
> > > And i also suggest to think about the big picture, how we can provide
> > > security throught this.
> > > Therefore we can implement security after this is done
> > >
> > > Are we going to secure albums based on album tags ?
> > >
> > > Regards
> > > Suho
> > >
> > > >
> > > >
> > > > On Sun, Nov 14, 2010 at 2:43 PM, Luciano Resende <
> luckbr1975@gmail.com
> > > > >wrote:
> > > >
> > > > > It would be great to understand the difference between high and low
> > > > > level here, particular because I don't think we need a very complex
> > > > > and deep API.
> > > > >
> > > >
> > >
> >
>
Re: Low level API
Posted by Suhothayan Sriskandarajah <su...@gmail.com>.
On 16 November 2010 20:07, Adriano Crestani <ad...@gmail.com>wrote:
> Hi Suhothayan,,
>
> Yes, my initial idea is to have privacy visibility defined per tag. Do you
> have any other suggestion?
>
> great
Since there is no JSON RPC calls and we are only dealing with REST, there
wont be much implications in implementing security to the rest branch. But
in order to provide security, each API calls need to be tested against the
corresponding session cookie, in order to check who calls the request, what
album is he accessing, and does he has permission to do so, etc...
For this to be successful, I Suggest we should come up with Security API
which will be published as services, and they will indeed call the low level
API that we are implementing.
Thoughts?
Regards
Suho
On Tue, Nov 16, 2010 at 11:29 AM, Suhothayan Sriskandarajah <
> suhothayan@gmail.com> wrote:
>
> > On 15 November 2010 00:49, Adriano Crestani <adrianocrestani@gmail.com
> > >wrote:
> >
> > > It would be great to understand the difference between high and low
> > > level here, particular because I don't think we need a very complex
> > > and deep API.
> > >
> > > High = API exposed as SOA service
> > > Low = API used by the service implementation to manipulate images and
> > tags
> > >
> > > You mentioned these are low level, then Gallery really seems high
> > > level. How about PhotoStream ?
> > >
> > > Gallery is low level according to the description I just gave above :)
> If
> > > you want to rename it to PhotoStream, for me it's OK.
> > >
> > > I'm not sure about the tag operations. Shouldn't this be like an
> > > "update" to the image "metadata" where you add a new tag to it ?
> > >
> > > That sounds reasonable too :)
> > >
> > > I'm not sure I understand this. To me, subscription and the actual
> > > gallery are decoupled.
> > >
> > > The sync operation needs to push the images retrieved from remote
> > provider
> > > to a gallery.
> > >
> > > Seems good
> > +1
> >
> > And i also suggest to think about the big picture, how we can provide
> > security throught this.
> > Therefore we can implement security after this is done
> >
> > Are we going to secure albums based on album tags ?
> >
> > Regards
> > Suho
> >
> > >
> > >
> > > On Sun, Nov 14, 2010 at 2:43 PM, Luciano Resende <luckbr1975@gmail.com
> > > >wrote:
> > >
> > > > It would be great to understand the difference between high and low
> > > > level here, particular because I don't think we need a very complex
> > > > and deep API.
> > > >
> > >
> >
>
Re: Low level API
Posted by Adriano Crestani <ad...@gmail.com>.
Hi Suhothayan,,
Yes, my initial idea is to have privacy visibility defined per tag. Do you
have any other suggestion?
On Tue, Nov 16, 2010 at 11:29 AM, Suhothayan Sriskandarajah <
suhothayan@gmail.com> wrote:
> On 15 November 2010 00:49, Adriano Crestani <adrianocrestani@gmail.com
> >wrote:
>
> > It would be great to understand the difference between high and low
> > level here, particular because I don't think we need a very complex
> > and deep API.
> >
> > High = API exposed as SOA service
> > Low = API used by the service implementation to manipulate images and
> tags
> >
> > You mentioned these are low level, then Gallery really seems high
> > level. How about PhotoStream ?
> >
> > Gallery is low level according to the description I just gave above :) If
> > you want to rename it to PhotoStream, for me it's OK.
> >
> > I'm not sure about the tag operations. Shouldn't this be like an
> > "update" to the image "metadata" where you add a new tag to it ?
> >
> > That sounds reasonable too :)
> >
> > I'm not sure I understand this. To me, subscription and the actual
> > gallery are decoupled.
> >
> > The sync operation needs to push the images retrieved from remote
> provider
> > to a gallery.
> >
> > Seems good
> +1
>
> And i also suggest to think about the big picture, how we can provide
> security throught this.
> Therefore we can implement security after this is done
>
> Are we going to secure albums based on album tags ?
>
> Regards
> Suho
>
> >
> >
> > On Sun, Nov 14, 2010 at 2:43 PM, Luciano Resende <luckbr1975@gmail.com
> > >wrote:
> >
> > > It would be great to understand the difference between high and low
> > > level here, particular because I don't think we need a very complex
> > > and deep API.
> > >
> >
>
Re: Low level API
Posted by Suhothayan Sriskandarajah <su...@gmail.com>.
On 15 November 2010 00:49, Adriano Crestani <ad...@gmail.com>wrote:
> It would be great to understand the difference between high and low
> level here, particular because I don't think we need a very complex
> and deep API.
>
> High = API exposed as SOA service
> Low = API used by the service implementation to manipulate images and tags
>
> You mentioned these are low level, then Gallery really seems high
> level. How about PhotoStream ?
>
> Gallery is low level according to the description I just gave above :) If
> you want to rename it to PhotoStream, for me it's OK.
>
> I'm not sure about the tag operations. Shouldn't this be like an
> "update" to the image "metadata" where you add a new tag to it ?
>
> That sounds reasonable too :)
>
> I'm not sure I understand this. To me, subscription and the actual
> gallery are decoupled.
>
> The sync operation needs to push the images retrieved from remote provider
> to a gallery.
>
> Seems good
+1
And i also suggest to think about the big picture, how we can provide
security throught this.
Therefore we can implement security after this is done
Are we going to secure albums based on album tags ?
Regards
Suho
>
>
> On Sun, Nov 14, 2010 at 2:43 PM, Luciano Resende <luckbr1975@gmail.com
> >wrote:
>
> > It would be great to understand the difference between high and low
> > level here, particular because I don't think we need a very complex
> > and deep API.
> >
>
Re: Low level API
Posted by Adriano Crestani <ad...@gmail.com>.
It would be great to understand the difference between high and low
level here, particular because I don't think we need a very complex
and deep API.
High = API exposed as SOA service
Low = API used by the service implementation to manipulate images and tags
You mentioned these are low level, then Gallery really seems high
level. How about PhotoStream ?
Gallery is low level according to the description I just gave above :) If
you want to rename it to PhotoStream, for me it's OK.
I'm not sure about the tag operations. Shouldn't this be like an
"update" to the image "metadata" where you add a new tag to it ?
That sounds reasonable too :)
I'm not sure I understand this. To me, subscription and the actual
gallery are decoupled.
The sync operation needs to push the images retrieved from remote provider
to a gallery.
On Sun, Nov 14, 2010 at 2:43 PM, Luciano Resende <lu...@gmail.com>wrote:
> It would be great to understand the difference between high and low
> level here, particular because I don't think we need a very complex
> and deep API.
>
Re: Low level API
Posted by Luciano Resende <lu...@gmail.com>.
On Sat, Nov 13, 2010 at 9:26 PM, Adriano Crestani
<ad...@gmail.com> wrote:
> Hi,
>
> Currently, every Photark component (jcr, security, search) exposes its
> functionalities as SOA services, so they can be easily wired together. I
> think at high level it's working well. However, at low level it's being very
> painful to introduce new features, since practically every implementation is
> coded directly in the service interface, making it very hardcoded.
>
I'm assuming you are mentioning this about the current trunk code :)
then I totally agree.
> Right now, we can see it happening when we try to add a new kind of remote
> album, which requires to change the gallery implementation and add a new
> condition block to handle each different type of photo provider. That's why
> I'm trying to identify each of these components and define common APIs to
> them.
>
This is what I had in mind for this :
- each albumProvider would have a "type"
- the aggregator would have a register per type (using a reference
with multiplicity 1..n)
- when providing services for a given provider, the aggregator would
get the provider by it's type and delegate
This should solve the issue you mentioned.
> At the same time, I'm trying to introduce a tagging system that should, at
> least at low level, replace the album system. Just to clarify, the main
> difference between tag and album is that photos are not contained in a tag,
> as it's contained in an album, instead, photos are contained directly in the
> gallery and they may have many tags. This means the same photo may be at the
> same time in the album "travel" and " favorite moments", I mean, it may be
> tagged by "travel" and "favorite moments". Using this tagging system at low
> level, we can still create an application that uses the old album concept,
> the application only needs to limit the number of tags applied to a photo to
> 1 and say "album" instead of "tag" :)
>
In general this seems very aligned to what I'm trying to do in the
rest branch, except that I was still having the concept of album...
but what you describe with the #tags seems reasonable.
> The interfaces below are only for use at low level. How their functionality
> will be exposed is up to the services (high level) API. Please, comments and
> suggestions about them are welcome :)
>
It would be great to understand the difference between high and low
level here, particular because I don't think we need a very complex
and deep API.
> /**
> * <p>
> * This interface should be implemented by every gallery implementation. It
> * provides methods to manipulate images' info and tags.
> * </p>
> *
> * <p>
> * The implementation is responsible to store the information about every
> tag
> * and image added to the gallery, and optionally its raw data.
> * </p>
> */
> public interface Gallery {
You mentioned these are low level, then Gallery really seems high
level. How about PhotoStream ?
>
> /**
> * Add image to the gallery. Only the information about the image, for raw
> * data, use {@link #uploadImage(byte[], String)}
> *
> * @return an image object containing the new image ID
> */
> Image addImage(Image image) throws PhotarkException;
>
> /**
> * Update an image information.
> */
> void updateImage(Image image) throws PhotarkException;
>
> /**
> * Update an image if it was previously aded using
> * {@link #uploadImage(byte[], String)}
> */
> void updateImageData(Image image, byte[] data) throws PhotarkException;
>
> /**
> * Remove an image from the gallery
> */
> void removeImage(String imageID) throws PhotarkException;
>
> /**
> * Upload a raw image data to the gallery. It works as
> * {@link #addImage(Image)}, but it also stores the raw image data for later
> * use.
> */
> Image uploadImage(byte[] data, String name) throws PhotarkException;
>
> /**
> * Add a tag to an image. If the tag does not exist in the gallery it's
> * automatically created.
> */
> void addTagToImage(String tagName, String imageID) throws PhotarkException;
>
> /**
> * Remove a tag from an image.
> */
> void removeTagFromImage(String tagName, String imageID)
> throws PhotarkException;
>
> /**
> * Update a tag info, adding description and a cover image to it. If the tag
> * doesn't exist yet in the gallery, it automatically added, otherwise its
> * information is just updated.
> */
> void updateTag(Tag tag) throws PhotarkException;
>
> /**
> * Remove a tag from the gallery. It's removed from every image its added as
> * well as its information (description and cover image).
> */
> void removeTag(String tagName) throws PhotarkException;
>
> /**
> * Returns all images available in the gallery ordered by its posted date.
> */
> List<Image> getImages() throws PhotarkException;
>
> /**
> * Returns all images containing the specified tag ordered by its posted
> date.
> */
> List<Image> getImagesByTag(String tagName) throws PhotarkException;
>
> /**
> * Returns all tags available in the gallery.
> */
> Set<Tag> getTags() throws PhotarkException;
>
> }
>
>
I'm not sure about the tag operations. Shouldn't this be like an
"update" to the image "metadata" where you add a new tag to it ?
> /**
> * This interfaces should be implemented by a gallery that supports search
> * queries.
> *
> * @see Gallery
> */
> public interface SearchableGallery extends Gallery {
>
> /**
> * Returns a query containing all images matching the given search query.
> * The returned images are ordered by an arbitrary relevance defined by the
> * gallery implementation.
> */
> List<Image> search(String query) throws PhotarkException;
>
> }
>
+1
> /**
> * <p>
> * The implementor of this interface is responsible for register/unregister
> * subscriptions to remote photo providers and synchronize the photos
> retrieve
> * from the remove providers with a gallery.
> * </p>
> * <p>
> * The implementation may use {@link PhotoStreamProvider} interface to
> access
> * the photo providers. How {@link PhotoStreamProvider}s are
> * registered is implementation independent.
> * </p>
> */
> public interface SubscriptionManager {
>
> /**
> * Adds a new subscription.
> *
> * @return a {@link SubscriptionConfig} object containing the new
> * subscription's ID
> */
> SubscriptionConfig addSubscription(SubscriptionConfig subscriptionConfig);
>
> /**
> * Updates a subscription information, like password, user, etc.
> */
> void updateSubscription(SubscriptionConfig subscriptionConfig);
>
> /**
> * Removes a subscription
> */
> void removeSubscription(String subscriptionID);
>
> /**
> * Synchronizes the photos retrieved from the given subscription with the
> * gallery.
> */
> void syncSubscription(String subscriptionID);
>
Ok
> /**
> * Returns the {@link Gallery} this {@link SubscriptionManager} synchronizes
> * the photos with.
> */
> Gallery getGallery();
>
I'm not sure I understand this. To me, subscription and the actual
gallery are decoupled.
> }
>
> public interface PhotoStreamProvider {
>
> String getProviderType();
>
> List<Image> getImages() throws PhotarkException;
>
> }
>
+1
In general it looks ok, I'd recommend two things :
1) Create a wiki which describes how these parts would glue together
2) Document the repository structure
3) Make sure you have a REST API in mind
The wiki page below can be a example
https://cwiki.apache.org/confluence/display/PHOTARKxWIKI/PhotArk+REST+API
--
Luciano Resende
http://people.apache.org/~lresende
http://twitter.com/lresende1975
http://lresende.blogspot.com/