FeedURLFactory.java

/* Copyright (c) 2006 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.google.api.gbase.client;

import java.io.UnsupportedEncodingException;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLEncoder;

/**
 * Provides feed URLs that can be used with a GoogleBase server.
 */
public class FeedURLFactory {

  /**
   * URL of the server to connect to by default.
   * Currently {@value #DEFAULT_BASE_URL}.
   */
  public static final String DEFAULT_BASE_URL =
      "http://www.google.com/base/";

  /** The url used as a base when creating urls. */
  private URL baseUrl;

  private URL feedSnippets;

  private URL feedItems;

  private URL feedItemsBatch;

  private URL feedLocales;

  private URL feedAttributes;

  private URL feedSnippetsBatch;

  /**
   * The default FeedURLFactory instance targeted
   * to the default URL.
   */
  private static final FeedURLFactory instance = new FeedURLFactory();


  /**
   * Gets the default instance of this factory, targeted
   * to {@value #DEFAULT_BASE_URL}.
   *
   * @return the default FeedURLFactory
   */
  public static FeedURLFactory getDefault() {
    return instance;
  }


  /**
   * Creates an URL factory targeted to {@value #DEFAULT_BASE_URL}.
   *
   * Access it using {@link #getDefault()}.
   */
  private FeedURLFactory() {
    try {
      init(DEFAULT_BASE_URL);
    } catch (MalformedURLException e) {
      throw new RuntimeException("Unexpected malformed URL", e);
    }
  }

  /**
   * Creates an URL factory targeted to a server.
   *
   * As long as you don't need to connect to a nonstandard
   * URL, different from {@value #DEFAULT_BASE_URL}, you should
   * consider calling {@link #getDefault()} instead.
   *
   * @param url an URL used as a base for the generated URLs
   * @throws MalformedURLException
   */
  public FeedURLFactory(String url) throws MalformedURLException {
    init(url);
  }
  
  private void init(String url) throws MalformedURLException {
    baseUrl = new URL(url);
    feedSnippets = new URL(baseUrl, "feeds/snippets/");
    feedSnippetsBatch = new URL(baseUrl, "feeds/snippets/batch");
    feedItems = new URL(baseUrl, "feeds/items/");
    feedItemsBatch = new URL(baseUrl, "feeds/items/batch");
    feedLocales = new URL(baseUrl, "feeds/locales/");
    feedAttributes = new URL(baseUrl, "feeds/attributes/");
  }

  /** Returns the URL used as a base for the generated URLs. */
  public URL getBaseURL() {
    return baseUrl;
  }
  
  /** 
   * Encodes a string using UTF-8. 
   * 
   * @param s string to be encoded
   * @throws RuntimeException when the JVM does not support UTF-8
   */
  private String encode(String s) {
    try {
      return URLEncoder.encode(s, "UTF-8");
    } catch (UnsupportedEncodingException e) {
      throw new RuntimeException("UTF-8 is not supported by the JVM", e);
    }
  }

  /**
   * Gets an URL for accessing a public feed, which allows users to perform
   * queries.
   * The formatting of the textual attributes returned by this feed
   * is not guaranteed. This is an unauthenticated read-only feed.
   *
   * @return an URL to be used when creating a {@link GoogleBaseQuery}
   */
  public URL getSnippetsFeedURL() {
    return feedSnippets;
  }

  /**
   * Gets an URL for accessing a public batch feed, which allows users to
   * get a series of entries.
   *
   * A query on this batch feed returns the same result as a series
   * of calls to {@link #getSnippetsFeedURL()} in one HTTP request.
   *
   * @return an URL to post a batch query to.
   */
  public URL getSnippetsBatchFeedURL() {
    return feedSnippetsBatch;
  }

  /**
   * Gets an URL for accessing a snippet.
   *
   * @see #getSnippetsFeedURL()
   * @param id the id of the snippet
   * @return an URL to be used when reading a snippet of an item with a
   *         {@link GoogleBaseService}
   * @throws MalformedURLException
   */
  public URL getSnippetsEntryURL(String id) throws MalformedURLException {
    if (id == null) {
      throw new NullPointerException("entryId is null");
    }
    return new URL(feedSnippets, encode(id));
  }

  /**
   * Gets an URL for accessing a customer feed, which allows users
   * to query, insert, update and delete their own items.
   * The textual attributes of the items are returned in their original format.
   * This is a read/write feed that is only accessible to authenticated users.
   *
   * @return an URL to be used for creating a {@link GoogleBaseQuery}
   */
  public URL getItemsFeedURL() {
    return feedItems;
  }

  /**
   * Gets an URL for accessing an item.
   *
   * @see #getItemsFeedURL()
   * @param entryId
   * @return an URL to be used when reading an item or when
   *         performing an update or delete operation with a
   *         {@link GoogleBaseService}
   * @throws MalformedURLException
   */
  public URL getItemsEntryURL(String entryId)
      throws MalformedURLException {
    if (entryId == null) {
      throw new NullPointerException("entryId is null");
    }
    return new URL(feedItems, encode(entryId));
  }


  /**
   * Gets an URL for posting batch operations
   * to the customer feed.
   *
   * @return an URL to be passed to
   *   {@link com.google.gdata.client.Service#batch(java.net.URL,
   *   com.google.gdata.data.BaseFeed)} 
   */
  public URL getItemsBatchFeedURL() {
    return feedItemsBatch;
  }

  /**
   * Gets the URL of the list of all the supported locales.
   * The feed is read-only and unauthenticated.
   *
   * @return an URL of a feed containing the supported locales
   */
  public URL getLocalesFeedURL() {
    return feedLocales;
  }

  /**
   * Gets an URL for querying the item types Google suggest using
   * for a given locale.
   * The feed is read-only and unauthenticated.
   *
   * @param locale a locale, for example "de_DE", "en_GB", "en_US"
   * @return an URL of a feed containing item types
   * @throws MalformedURLException
   */
  public URL getItemTypesFeedURL(String locale) throws MalformedURLException {
    if (locale == null) {
      throw new NullPointerException("locale is null");
    }
    return new URL(baseUrl, "feeds/itemtypes/" + encode(locale));
  }

  /**
   * Gets an URL for getting the item types Google suggest using
   * for a given itemtype for a given locale.
   * The feed is read-only and unauthenticated.
   *
   * @param locale a locale, for example "de_DE", "en_GB", "en_US"
   * @param itemType the item type to be analysed
   * @return an URL of a feed containing item types
   * @throws MalformedURLException
   */
  public URL getItemTypesEntryURL(String locale,
                                  String itemType) 
      throws MalformedURLException {
    if (locale == null) {
      throw new NullPointerException("locale is null");
    }
    if (itemType == null) {
      throw new NullPointerException("itemType is null");
    }
    return new URL(baseUrl, "feeds/itemtypes/" + encode(locale) +
                            "/" + encode(itemType));
  }

  /**
   * Gets an URL for the list of the most used attributes
   * and their most used values.
   *
   * @return an URL to be used for creating a {@link GoogleBaseQuery}
   */
  public URL getAttributesFeedURL() {
    return feedAttributes;
  }
}