001/*
002 * Shredzone Commons
003 *
004 * Copyright (C) 2012 Richard "Shred" Körber
005 *   http://commons.shredzone.org
006 *
007 * This program is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU Library General Public License as
009 * published by the Free Software Foundation, either version 3 of the
010 * License, or (at your option) any later version.
011 *
012 * This program is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
015 * GNU General Public License for more details.
016 *
017 * You should have received a copy of the GNU Library General Public License
018 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
019 */
020
021package org.shredzone.commons.gravatar;
022
023import java.io.File;
024import java.io.IOException;
025
026/**
027 * A service for accessing Gravatar avatars.
028 *
029 * @author Richard "Shred" Körber
030 */
031public interface GravatarService {
032
033    /**
034     * Computes the Gravatar hash for a mail address. Actually, this is the md5 sum of the
035     * mail address.
036     *
037     * @param mail
038     *            Mail address to hash
039     * @return Gravatar hash
040     */
041    String computeHash(String mail);
042
043    /**
044     * Fetch a File of the Gravatar image for the given hash. If there is no such file,
045     * the image is downloaded from the Gravatar server, and stored in the file system.
046     * <p>
047     * The files are cached for a certain time.
048     *
049     * @param hash
050     *            Gravatar image hash
051     * @return File containing the image
052     */
053    File fetchGravatar(String hash) throws IOException;
054
055}