org.jickr
Class Photo

java.lang.Object
  extended by org.jickr.Photo
All Implemented Interfaces:
java.lang.Comparable<Photo>

public class Photo
extends java.lang.Object
implements java.lang.Comparable<Photo>

Encapsulates Photo information. Includes a few static methods to search for photos. Keeps a cache of the backing Images, adjustable in size by the user. Photo objects are typically created via a find method, via the search method, or, less commonly, by supplying the id (and possibly the secret) in a constructor.


Nested Class Summary
static class Photo.Allowed
          List of possible permissions allowed for a Photo.
 class Photo.PhotoSize
          PhotoSize encapsulates information for a certain size of a photo.
static class Photo.Size
          List of possibly valid Photo sizes.
 
Constructor Summary
Photo(java.lang.String id)
          Sometimes, all you know is the PhotoID - if you are authenticated, with READ privlege on the photo in question (or if the Photo is public), this is enough to get the Photo information.
Photo(java.lang.String id, java.lang.String secret)
          If you know the ID and the Secret of a photo, you can use it to create a new Photo object.
 
Method Summary
 java.lang.String addComment(java.lang.String commentText)
          Adds a comment to this Photo, returns the new comment ID.
 void addFavorite()
          Add this photo as favorite to the authenticated user.
 java.lang.String addNote(java.awt.Rectangle area, java.lang.String text)
          Add a Note to a Photo.
 void addTags(java.lang.String tags)
          Adds tags to this Photo.
 boolean canAddMeta()
          Returns whether someone with the authenticated user's permissions can add metadata to the photo.
 boolean canComment()
          Returns whether someone with the authenticated user's permissions can comment on the photo.
 int compareTo(Photo p)
          Compares a Photo's image.
static Photo create(java.io.File imageFile, java.lang.String title)
          Create a new Photo on Flickr.
static Photo create(java.io.File imageFile, java.lang.String title, java.lang.String desc, java.lang.String tags, boolean pub, boolean friend, boolean family)
          Create a new Photo on Flickr.
 void delete()
          Delete this photo from Flickr.
 boolean equals(java.lang.Object o)
          Determine of a Photo is equal to another.
static Photo findByID(java.lang.String id, java.lang.String secret)
          Get a photo, provided you have the Photo's id, and secret key.
static java.util.List<Photo> findByTags(java.lang.String tags)
          Get a list of photos that are tagged with the desired keywords.
static java.util.List<Photo> findByTags(java.lang.String tags, boolean join)
          Get a list of Photos that are tagged with the desired keywords.
 java.util.List<Comment> getComments()
          Get a list of comments for this photo.
 java.util.Date getDateTaken()
          Get the date the photo was taken.
 java.lang.String getDateTakenGranularity()
          Get the granularity (i.e., the precision) of the date the photo was taken.
 java.util.Date getDateUpdated()
          Get the date the photo was last updated.
 java.util.Date getDateUploaded()
          Get the date the photo was uploaded to Flickr.
 java.lang.String getDescription()
          Get the description of the photo.
 org.jdom.Document getEXIF()
          Get the EXIF data for this photo.
 java.lang.String getID()
          Get the id of the photo.
 java.awt.image.BufferedImage getImage()
          Get a BufferedImage of this photo (default size).
 java.awt.image.BufferedImage getImage(Photo.Size size)
          Get a BufferedImage of this photo.
static java.util.List<Photo> getInteresting()
          Gets a list of Photos that Flickr users find interesting, for today.
static org.jickr.PhotoList getInteresting(java.util.Calendar cal)
          Gets a list of Photos that Flickr users find interesting, for today.
 License getLicense()
          Get the license of the photo.
 java.util.List<Note> getNotes()
          Get a list of notes for this Photo.
 int getNumComments()
          Get the number of comments attached to this photo in Flickr.
 java.net.URL getPhotoPage()
          Get the Flickr URL of the page where you can find this photo.
 java.util.List<Group> getPublicGroups()
          Get a list of all public Groups this Photo belongs to.
 java.util.List<PhotoSet> getPublicSets()
          Get a list of all public PhotoSets this Photo belongs to.
static java.util.List<Photo> getRecentPhotos()
          Gets a list of the most recent photos on Flickr.
 java.lang.String getSecret()
          Get the secret key of the photo.
 java.util.Map<Photo.Size,Photo.PhotoSize> getSizes()
          Get a Map of all valid PhotoSize values for this Photo.
 java.net.URL getStaticURL()
          Get the static Flickr URL where you can find this photo.
 java.util.List<Tag> getTags()
          Get a list of tags for this Photo.
 java.lang.String getTitle()
          Get the title of the photo.
 int hashCode()
          Get the hashcode for this object.
 boolean isFamily()
          Returns whether the photo is visible to people marked as family of the authenticated user.
 boolean isFriend()
          Returns whether the photo is visible to people marked as friends of the authenticated user.
 boolean isPublic()
          Return whether the photo is publicly visible.
 void removeFavorite()
          Remove this photo from the authenticated user's list of favorites.
 void replace(java.io.File imageFile)
          Replaces the Photo on Flickr with the Image provided.
 void rotate(int amount)
          Rotate the Photo on Flickr.
static java.util.List<Photo> search(PhotoSearch search)
          Get a list of Photos associated with the PhotoSearch term.
 void setDateTaken(java.util.Date dateTaken)
          Update the date Flickr lists as the date taken for the Photo.
 void setDateTakenGranularity(java.lang.String granularity)
          Update the date Flickr lists as the date taken for the Photo.
 void setDateUploaded(java.util.Date dateUploaded)
          Update the date Flickr lists as the date the Photo was uploaded.
 void setLicense(License license)
          Sets the license restrictions of this photo.
 void setPerms(boolean pub, boolean friends, boolean family, Photo.Allowed comment, Photo.Allowed addmeta)
          Set permissions on a Photo.
 void setTags(java.lang.String tags)
          Replace all tags on the Photo with the specified tags.
 java.lang.String toString()
          Get the String representation of the URL for this photo.
 void updateTitleDesc(java.lang.String title, java.lang.String desc)
          Change the title text and description text associated with a Photo.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Photo

public Photo(java.lang.String id,
             java.lang.String secret)
If you know the ID and the Secret of a photo, you can use it to create a new Photo object. Typically, you'll get new Photo objects by calling static methods, but this constructor is useful when you know just the photo you want. Note: This call does not check with Flickr before the object is created.

Parameters:
id - ID of the photo. Must not be null.
secret - Secret string of the photo. Needed for private photos.

Photo

public Photo(java.lang.String id)
Sometimes, all you know is the PhotoID - if you are authenticated, with READ privlege on the photo in question (or if the Photo is public), this is enough to get the Photo information. Note: This call does not check with Flickr before the object is created.

Parameters:
id - ID of the Photo. Must not be null.
Method Detail

findByID

public static Photo findByID(java.lang.String id,
                             java.lang.String secret)
                      throws FlickrException
Get a photo, provided you have the Photo's id, and secret key.

Returns:
The Photo object described by the key and secret.
Throws:
FlickrException

findByTags

public static java.util.List<Photo> findByTags(java.lang.String tags)
                                        throws FlickrException
Get a list of photos that are tagged with the desired keywords.

Parameters:
tags - Comma separated list of tags
Throws:
FlicrException - For any error.
FlickrException

findByTags

public static java.util.List<Photo> findByTags(java.lang.String tags,
                                               boolean join)
                                        throws FlickrException
Get a list of Photos that are tagged with the desired keywords.

Parameters:
tags - Comma separated list of tags
join - True joins the tags with AND, False joins the tags with OR
Throws:
FlickrException - For any error.

search

public static java.util.List<Photo> search(PhotoSearch search)
                                    throws FlickrException
Get a list of Photos associated with the PhotoSearch term. Unauthenticated calls return only public photos. If authenticated at READ level or above, private photos visible to the authenticated user can be viewed as well.

Parameters:
search - A PhotoSearch object describing the search to perform.
Returns:
A list of Photos corresponding to the search term supplied.
Throws:
FlickrExcpetion - For any error.
FlickrException

getRecentPhotos

public static java.util.List<Photo> getRecentPhotos()
                                             throws FlickrException
Gets a list of the most recent photos on Flickr.

Returns:
A PhotoList of Flickr's recent photos
Throws:
FlickrException

getInteresting

public static java.util.List<Photo> getInteresting()
                                            throws FlickrException
Gets a list of Photos that Flickr users find interesting, for today.

Returns:
A PhotoList of Flickr's interesting photos.
Throws:
FlickrException

getInteresting

public static org.jickr.PhotoList getInteresting(java.util.Calendar cal)
                                          throws FlickrException
Gets a list of Photos that Flickr users find interesting, for today.

Parameters:
cal - - Used to specify what date to fetch interesting photos from.
Returns:
A PhotoList of FJickrs interesting photos.
Throws:
FlickrException

create

public static Photo create(java.io.File imageFile,
                           java.lang.String title)
                    throws FlickrException
Create a new Photo on Flickr. This photo will be created as a JPG. Convenience method for longer call. This method requires WRITE level authentication.

Parameters:
imageFile - Image to use as the basis for the Photo.
title - Title of the Photo. May be null.
Returns:
The Photo created.
Throws:
FlickrException - on any error.

create

public static Photo create(java.io.File imageFile,
                           java.lang.String title,
                           java.lang.String desc,
                           java.lang.String tags,
                           boolean pub,
                           boolean friend,
                           boolean family)
                    throws FlickrException
Create a new Photo on Flickr. This photo will be created as a JPG. This method requires WRITE level authentication.

Parameters:
imageFile - Image to use as the basis for the Photo. Must be a JPEG formatted file.
title - Title of the Photo. May be null.
desc - Description of the Photo. May be null.
tags - Space delimited list of tags for the Photo.
pub - Whether this photo is publicly viewable.
friend - Whether this photo is viewable by people marked as Friends.
family - Whether this photo is viewable by people marked as Family.
Returns:
Photo object created.
Throws:
FlickrException - on any error.

replace

public void replace(java.io.File imageFile)
             throws FlickrException
Replaces the Photo on Flickr with the Image provided. Image must be JPG (sorry). This call requires WRITE level authentication. This call requires that the authenticated user be a Pro level account.

Parameters:
imageFile - The new image to store for this Photo.
Throws:
FlickrException - on any error.

delete

public void delete()
            throws FlickrException
Delete this photo from Flickr. Not suprisingly, it requires DELETE level authentication. The object will be invalid after deletion, and no further actions may be performed on it.

Throws:
FlickrException - on any error.

getStaticURL

public java.net.URL getStaticURL()
                          throws FlickrException
Get the static Flickr URL where you can find this photo. (i.e., the URL that returns the actual image.) This call returns the default sized photo. To get the page you see in a browser, use PhotoSize.getPage(). To get different sizes TODO: ADD CODE SNIP

Please note: Flickr requires that if you display an image from this Photo in a webpage, that you make it a link to the URL returned from Photo.getPhotoPage(). Please do the right thing.

Returns:
URL of the default static link for this photo.
Throws:
FlickrException
See Also:
getPhotoPage()

getPhotoPage

public java.net.URL getPhotoPage()
                          throws FlickrException
Get the Flickr URL of the page where you can find this photo. (i.e., the URL that returns the page where this image is displayed.) This call returns the default sized photo.

Returns:
URL of the default page for this photo.
Throws:
FlickrException
See Also:
getStaticURL()

getTitle

public java.lang.String getTitle()
                          throws FlickrException
Get the title of the photo.

Returns:
title - The title of the Photo.
Throws:
FlickrException - on an access error to Flickr.

getSecret

public java.lang.String getSecret()
                           throws FlickrException
Get the secret key of the photo.

Returns:
The secret key of the Photo.
Throws:
FlickrException

getID

public java.lang.String getID()
Get the id of the photo. You need this and the secret key to the retreive the Photo.

Returns:
The id of the Photo.

getDescription

public java.lang.String getDescription()
                                throws FlickrException
Get the description of the photo.

Returns:
The Description Text for this Flickr Photo.
Throws:
FlickrException

getLicense

public License getLicense()
                   throws FlickrException
Get the license of the photo.

Returns:
The license for this Flickr Photo.
Throws:
FlickrException

setLicense

public void setLicense(License license)
                throws FlickrException
Sets the license restrictions of this photo.

Requires WRITE authentication and permission.

Parameters:
license - License to use for this Photo.
Throws:
FlickrException - on any error.

getNumComments

public int getNumComments()
                   throws FlickrException
Get the number of comments attached to this photo in Flickr. This value is cached - it's only checked once. If you expect the value to change, use Photo.getComments.size() instead, though that will be more expensive.

Returns:
The total number of comments associated with this Photo
Throws:
FlickrException
See Also:
getComments()

getDateUploaded

public java.util.Date getDateUploaded()
                               throws FlickrException
Get the date the photo was uploaded to Flickr.

Returns:
The date this photo was uploaded.
Throws:
FlickrException

getDateUpdated

public java.util.Date getDateUpdated()
                              throws FlickrException
Get the date the photo was last updated. This value is cached, and not updated for the life of the object.

Returns:
The date this photo was last updated on Flickr.
Throws:
FlickrException

getDateTaken

public java.util.Date getDateTaken()
                            throws FlickrException
Get the date the photo was taken.

Returns:
The date this photo was taken.
Throws:
FlickrException

getDateTakenGranularity

public java.lang.String getDateTakenGranularity()
                                         throws FlickrException

Get the granularity (i.e., the precision) of the date the photo was taken.

Currently has three values: 0: granularity to the second, 4: granularity to the month, and 6: granularity to the year. Later updates to Flickr may return any value between 0 and 10.

Currently returned as a String. This may change to an int at some time in the future, if there's a need.

Returns:
Code indicating the precision of the date taken.
Throws:
FlickrException - on any error.

getImage

public java.awt.image.BufferedImage getImage()
                                      throws java.io.IOException,
                                             FlickrException
Get a BufferedImage of this photo (default size). This response is cached, as in Photo.getImage(Size).

Returns:
image Image of this photo.
Throws:
java.io.IOException
FlickrException
See Also:
getImage(Size)

getImage

public java.awt.image.BufferedImage getImage(Photo.Size size)
                                      throws FlickrException
Get a BufferedImage of this photo. This response is cached - the cache is currently limited to a single size per Photo object.

Parameters:
size - - Size of the image to fetch.
Returns:
image Image of this photo.
Throws:
FlickrException

getEXIF

public org.jdom.Document getEXIF()
                          throws FlickrException
Get the EXIF data for this photo. This is returned as a JDOM Document, since it can vary so very much. If you have better suggestions for how to handle this call, please tell me at dev@jickr.dev.java.net.

This call is not cached, and goes out to Flickr every time to check data.

Returns:
A Document containing all EXIF data.
Throws:
FlickrException - on any error.

getComments

public java.util.List<Comment> getComments()
                                    throws FlickrException
Get a list of comments for this photo.

Returns:
A list of Comment objects for this Photo.
Throws:
FlickrException - in the event of any error.

getSizes

public java.util.Map<Photo.Size,Photo.PhotoSize> getSizes()
                                                   throws FlickrException
Get a Map of all valid PhotoSize values for this Photo.

Returns:
A Map of all the different Sizes for this Photo.
Throws:
FlickrException - on any error.

addComment

public java.lang.String addComment(java.lang.String commentText)
                            throws FlickrException

Adds a comment to this Photo, returns the new comment ID. Since Flickr doesn't offer a way to search for a comment via ID, the user will have to do a getComments() and search for the comment with Comment.getID() if they want a Comment object representing this added comment.

This call requires that the user be authenticated at the WRITE level.

Parameters:
commentText - Text for the comment to add.
Returns:
The comment's ID string
Throws:
FlickrException - in the event of a failure. Note that if an exception is thrown, it's possible (thought unlikely) that a comment was added anyway.
See Also:
getComments(), Comment.getID()

addFavorite

public void addFavorite()
                 throws FlickrException
Add this photo as favorite to the authenticated user.

Throws:
FlickrException - on any error.

removeFavorite

public void removeFavorite()
                    throws FlickrException
Remove this photo from the authenticated user's list of favorites.

Throws:
FlickrException - on any error.

getPublicSets

public java.util.List<PhotoSet> getPublicSets()
                                       throws FlickrException
Get a list of all public PhotoSets this Photo belongs to. This value is not cached - it returns the current list of PhotoSets with every call.

Returns:
A list of PhotoSet objects this Photo is associated with. Returns an empty list if none found.
Throws:
FlickrException - on any error.

getPublicGroups

public java.util.List<Group> getPublicGroups()
                                      throws FlickrException
Get a list of all public Groups this Photo belongs to. This value is not cached - it returns the current list of Groups with every call.

Returns:
A list of Group objects this Photo is associated with. Returns an empty list if none found.
Throws:
FlickrException - on any error.

getTags

public java.util.List<Tag> getTags()
                            throws FlickrException
Get a list of tags for this Photo. This value is not cached - it returns the current list of tags with every call.

Returns:
A list of Tag objects associated with this Photo.
Throws:
FlickrException - on any error.

addTags

public void addTags(java.lang.String tags)
             throws FlickrException
Adds tags to this Photo. How the parameter is treated is up to Flickr - for instance, Flickr's documentation says that this is a "comma-delimited list", but spaces seem to delimit new tags as well, such that "New Test Tag" creates 3 new tags, called "New" "Test" and "Tag".

Parameters:
tags - A comma delimited list of tags to add.
Throws:
FlickrException - on any error.

setTags

public void setTags(java.lang.String tags)
             throws FlickrException
Replace all tags on the Photo with the specified tags. Requires WRITE level authenticated access.

Parameters:
tags - A comma delimited list of tags.
Throws:
FlickrException - on any error.

getNotes

public java.util.List<Note> getNotes()
                              throws FlickrException
Get a list of notes for this Photo. This value is not cached - it returns the current list of notes with every call.

Returns:
A list of Note objects associated with this Photo.
Throws:
FlickrException - on any error.

addNote

public java.lang.String addNote(java.awt.Rectangle area,
                                java.lang.String text)
                         throws FlickrException
Add a Note to a Photo. Coordinates for the area are in pixels, based on the 500px image size shown on individual photo pages.

Parameters:
area - Rectangle describing the area covered by the note. Must not be null.
text - Text of the note. Must not be null.
Returns:
The id of the Note created. You'll have to look it up if you want a Note object. This is done for performance.
Throws:
FlickrException - on any error.

updateTitleDesc

public void updateTitleDesc(java.lang.String title,
                            java.lang.String desc)
                     throws FlickrException
Change the title text and description text associated with a Photo. Requires WRITE level authentication.

Parameters:
title - The new title for the photo. May not be null.
desc - The new description for the photo. May not be null.
Throws:
FlickrException - on any error.

setDateUploaded

public void setDateUploaded(java.util.Date dateUploaded)
                     throws FlickrException
Update the date Flickr lists as the date the Photo was uploaded. Requires WRITE level authentication.

Parameters:
dateUploaded - The new date to list as the date uploaded. May not be null.
Throws:
FlickrException - on any error.

setDateTaken

public void setDateTaken(java.util.Date dateTaken)
                  throws FlickrException
Update the date Flickr lists as the date taken for the Photo. Requires WRITE level authentication.

Parameters:
dateTaken - The new date to list as the date uploaded. May not be null.
Throws:
FlickrException - on any error.

setDateTakenGranularity

public void setDateTakenGranularity(java.lang.String granularity)
                             throws FlickrException
Update the date Flickr lists as the date taken for the Photo. Requires WRITE level authentication. Granularity may be one of: 0: precision to the second, 4: precision to the month, 6: precision to the year.

Parameters:
granularity - The precision of the date taken on Flickr. May not be null. Must be one of 0, 4 or 6.
Throws:
FlickrException - on any error.

rotate

public void rotate(int amount)
            throws FlickrException

Rotate the Photo on Flickr.

Requires authentication with WRITE access.

NOTE: This seems to be a very expensive call.

Parameters:
amount - The amount, in degrees, to rotate the photo. Must be one of 90, 180, 270.
Throws:
FlickrException - on any error.

isPublic

public boolean isPublic()
                 throws FlickrException
Return whether the photo is publicly visible.

Requires authentication with read access.

Returns:
Whether a photo is public.
Throws:
FlickrException - on any error.

isFriend

public boolean isFriend()
                 throws FlickrException
Returns whether the photo is visible to people marked as friends of the authenticated user.

Requires authentication with READ access.

Returns:
Whether a photo is visible to people marked as friends.
Throws:
FlickrException - on any error.

isFamily

public boolean isFamily()
                 throws FlickrException
Returns whether the photo is visible to people marked as family of the authenticated user.

Requires authentication with READ access.

Returns:
Whether a photo is visible to people marked as family.
Throws:
FlickrException - on any error.

canComment

public boolean canComment()
                   throws FlickrException
Returns whether someone with the authenticated user's permissions can comment on the photo.

Requires authentication with READ access.

Returns:
Whether a photo can have comments added to it by the authenticated user.
Throws:
FlickrException - on any error.

canAddMeta

public boolean canAddMeta()
                   throws FlickrException
Returns whether someone with the authenticated user's permissions can add metadata to the photo. Metadata includes Notes and Tags.

Requires authentication with READ access.

Returns:
Whether a photo can have metadata added to it by the authenticated user.
Throws:
FlickrException - on any error.

setPerms

public void setPerms(boolean pub,
                     boolean friends,
                     boolean family,
                     Photo.Allowed comment,
                     Photo.Allowed addmeta)
              throws FlickrException
Set permissions on a Photo.

Requires authentication with WRITE access.

Parameters:
pub - Is the public allowed to view the photo?
friends - Are friends allowed to view the photo?
family - Are family allowed to view the photo?
comment - Who can comment on the photo?
addmeta - Who can add Notes and Tags to a photo?
Throws:
FlickrException - on any error.

toString

public java.lang.String toString()
Get the String representation of the URL for this photo.

Overrides:
toString in class java.lang.Object
Returns:
String representing this Photo. Using the URL for this purpose.

equals

public boolean equals(java.lang.Object o)
Determine of a Photo is equal to another.

Overrides:
equals in class java.lang.Object
Returns:
Whether a Photo object represents the same photo

hashCode

public int hashCode()
Get the hashcode for this object.

Overrides:
hashCode in class java.lang.Object

compareTo

public int compareTo(Photo p)
Compares a Photo's image. Uses the Date the Photo's image object was created to compare. (Note: Not the date of the photo, but the creatation date and time of the Java Object). Return is the same as for java.util.Date. TODO: Yes, this doesn't actually do what you'd expect. I need to fix this at some point to return something a little more rational, or hide it. In particular, equals uses a different equality metric, so I've got to deal with that at some point.

Specified by:
compareTo in interface java.lang.Comparable<Photo>
Returns:
comparison <1 if Photo newer than supplied photo, 0 if the same, 1 if older.