Kind.java

/* Copyright (c) 2008 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.gdata.data;

import com.google.gdata.util.Namespaces;
import com.google.gdata.util.ServiceException;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.IOException;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import java.lang.reflect.Constructor;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * The Kind class defines annotation types, interfaces and static helper 
 * methods for GData Kind extension handling.  A GData <i>Kind</i> refers to 
 * a specific extension profile configuration for an Atom feed/entry or RSS 
 * channel/item.
 *
 * 
 */
public class Kind {

  /**
   * The location of the <code>META-INF</code> jar directory where GData kind
   * mapping information is stored.
   */
  public static final String META_DIRECTORY = "META-INF/gdata/kinds/";
  
  /**
   * Caches the mappings from a kind term to the {@link Adaptor} classes that
   * handle the kind.  Since these are configured by JAR-based metadata,
   * they are guaranteed to be constant once loaded unless/until the
   * classloader for GData java library is bounced.
   */
  private static Map<String, List<Class<Adaptor>>> kindAdaptors =
      new HashMap<String, List<Class<Adaptor>>>();

  /**
   * The Term annnotation type is used to annotate {@link Adaptor}
   * classes to declare the GData kind {@link Category} term value(s)
   * implemented by the adaptor type.
   */
  @Target(ElementType.TYPE)
  public @interface Term {

    /**
     * Specifies the term value within the {link Namespace.gKind} scheme
     * that is handled by the {@link Adaptor} class.
     */
    public String value();
  }

  /**
   * The Adaptable interface is implemented by GData {@link ExtensionPoint}
   * types that can be flexible adapted based upon the presence of GData
   * kind category elements.
   */
  public interface Adaptable {

    /**
     * Associates a new {@link Adaptor} with this {@code Adaptable} instance.
     */
    void addAdaptor(Adaptor adaptor);

    /**
     * Returns the collection of {@link Adaptor} instances associated with the
     * this {@code Adaptable} instance.
     */
    Collection<Adaptor> getAdaptors();

    /**
     * Returns a {@link Adaptor} instance associated with this
     * {@code Adaptable} instance of the specified type, or {code null}
     * if none is available..
     */
    <E extends Adaptor> E getAdaptor(Class<E> adaptorClass);
  }

  /**
   * The Adaptor interface is implemented by {@link Extension} classes
   * that provide extension declaration and data modeling support for 
   * specific GData kinds.
   */
  public interface Adaptor {

    /**
     * Declares the {@link ExtensionDescription} of each {@link Extension}
     * expected by the implementing {@link ExtensionPoint} in the target
     * profile.  This API should generally not be called directly by clients;
     * the {@link ExtensionProfile#addDeclarations(Kind.Adaptor)} method should
     * be used to declare extensions.
     *
     * @param extProfile the profile that should be extended.
     * @see ExtensionProfile#addDeclarations(Kind.Adaptor)
     */
    void declareExtensions(ExtensionProfile extProfile);
  }

  /**
   * A simple helper class implementation of the {@link Adaptable} interface.
   * Classes that need to implement {@code Adaptable} can construct an
   * instance of this class and delegate to it.
   */
  public static class AdaptableHelper implements Adaptable {

    private List<Kind.Adaptor> adaptors = new ArrayList<Kind.Adaptor>();

    public void addAdaptor(Kind.Adaptor adaptor) {
      adaptors.add(adaptor);
    }

    public Collection<Kind.Adaptor> getAdaptors() {
      return adaptors;
    }

    public <E extends Kind.Adaptor> E getAdaptor(Class<E> adaptorClass) {
      for (Kind.Adaptor adaptor : adaptors) {
        if (adaptor.getClass().equals(adaptorClass)) {
          return adaptorClass.cast(adaptor);
        }
      }
      return null;
    }
  }

  /**
   * The AdaptorException class defines a simple {@link ServiceException}
   * type that is thrown on kind adaptation failures.
   */
  public static class AdaptorException extends ServiceException {

    public AdaptorException(String message) {
      super(message);
      setHttpErrorCodeOverride(HttpURLConnection.HTTP_INTERNAL_ERROR);
    }

    public AdaptorException(String message, Throwable cause) {
      super(message, cause);
      setHttpErrorCodeOverride(HttpURLConnection.HTTP_INTERNAL_ERROR);
    }

    public AdaptorException(Throwable cause) {
      super(cause);
      setHttpErrorCodeOverride(HttpURLConnection.HTTP_INTERNAL_ERROR);
    }
  }

  public static boolean isKindCategory(Category category) {
    return Namespaces.gKind.equals(category.getScheme());
  }

  /**
   * Returns the kind service name associatd with a particular Kind category
   * term value.  It converts a kind term URI to a service file name that
   * is used for dynamic discovery of {@link Adaptor} class implementations
   * for the kind.
   */
  public static String getKindServiceName(String kindTerm) {

    StringBuilder serviceName = new StringBuilder(kindTerm.length());
    try {
      URL termUrl = new URL(kindTerm);

      // Invert any dotted components of the host name
      String [] hostComponents = termUrl.getHost().split("\\W");
      int lastIndex = hostComponents.length - 1;
      for (int i = lastIndex; i >= 0; i--) {
        if (i != lastIndex) {
          serviceName.append(".");
        }
        serviceName.append(hostComponents[i]);
      }

      // Convert the path, substituting dot separators for path
      // element separators
      String [] pathComponents = termUrl.getPath().split("\\W");
      for (int i = 0; i < pathComponents.length; i++) {
        if (pathComponents[i].length() > 0) {
          serviceName.append(".");
          serviceName.append(pathComponents[i]);
        }
      }

      // Convert the ref (if any), substituting dot separators.
      if (termUrl.getRef() != null) {
        String [] refComponents = termUrl.getRef().split("\\W");
        for (int i = 0; i < refComponents.length; i++) {
          if (refComponents[i].length() > 0) {
            serviceName.append(".");
            serviceName.append(refComponents[i]);
          }
        }
      }


    } catch (java.net.MalformedURLException mue) {
      throw new IllegalArgumentException("Kind term must be a valid URL", mue);
    }
    return serviceName.toString();
  }

  /**
   * Returns that {@link Adaptor} class that handles the
   * declaration of extensions within an {@link ExtensionProfile} based
   * upon the kind term value.  A return value of {@code null} indicates
   * that no adaptor class could be located for this cobintation of kind and
   * {@link Adaptable} type.
   */
  public static Class<Adaptor> getAdaptorClass(String kindTerm,
                                               Adaptable adaptable)
      throws AdaptorException {

    ClassLoader cl = adaptable.getClass().getClassLoader();

    List<Class<Adaptor>> adaptorList = kindAdaptors.get(kindTerm);
    if (adaptorList == null) {
      // Lazily load the adaptor list for a kind on first usage and store
      // in the cache.
      adaptorList = new ArrayList<Class<Adaptor>>();
      String termService = getKindServiceName(kindTerm);
      InputStream serviceStream;
      try {
        serviceStream = cl.getResourceAsStream(META_DIRECTORY
            + termService);
        if (serviceStream == null) {
          return null;
        }
        BufferedReader rdr =
          new BufferedReader(new InputStreamReader(serviceStream));
        String line;
        while ((line = rdr.readLine()) != null) {
          if (line.charAt(0) == '#') {  // comment line
            continue;
          }
          
          adaptorList.add((Class<Adaptor>) cl.loadClass(line));
        }
      } catch (IOException ioe) {
        throw new AdaptorException("Unable to load Adaptor service info", ioe);
      } catch (ClassNotFoundException cnfe) {
        throw new AdaptorException("Unable to load Adaptor class", cnfe);
      }
      kindAdaptors.put(kindTerm, adaptorList);
    }

    // A mix-in adaptor type will only have one mapping, that can be used
    // for all valid contexts since it doesn't rely upon inheritance.
    if (adaptorList.size() == 1) {
      return adaptorList.get(0);
    }

    Class<Adaptor> adaptorclass = null;

    // Inheritance based adaptation:  Look for Adaptor instance that shares
    // a superclass relationship with the input Adaptable (for example,
    // both derive from BaseFeed).
    for (Class<Adaptor> adaptorClass : adaptorList) {
      Class<? extends Adaptable> checkClass = adaptable.getClass();
      while (Adaptable.class.isAssignableFrom(checkClass)) {
        if (checkClass.isAssignableFrom(adaptorClass)) {
          return adaptorClass;
        }
        checkClass = (Class<? extends Adaptable>) checkClass.getSuperclass();
      }
    }
    return null;
  }

  /**
   * Returns an {@link Adaptor} instance associated with the specified
   * kind that is associated with the target {@link Adaptable}.  Returns
   * {@code null} if no Adaptor can be found.
   */
  static public Adaptor getAdaptor(String kindTerm, Adaptable adaptable) 
      throws AdaptorException {

    Class<Adaptor> adaptorClass = getAdaptorClass(kindTerm, adaptable);
    if (adaptorClass == null) {
      return null;
    }
    Adaptor adaptor = adaptable.getAdaptor(adaptorClass);
    if (adaptor == null) {

      // Look for an adaptor constructor that can take the adaptable
      // instance as an argument.
      Constructor<?> adaptorConstructor = null;
      Class<?> constructorArgClass = adaptable.getClass();
      while (constructorArgClass != null) {
        try {
          adaptorConstructor = adaptorClass.getConstructor(constructorArgClass);
          break;
        } catch (NoSuchMethodException nsme) {
          // Move on to parent of adaptor class and check again
          constructorArgClass = constructorArgClass.getSuperclass();
        }
      }

      // If not found, look for one with a null-arg constructor.  This
      // means it is a mix-in style kind, rather than an entry or feed
      // extension.
      if (adaptorConstructor == null) {
        try {
          adaptorConstructor = adaptorClass.getConstructor();
        } catch (NoSuchMethodException nsme) {
          throw new AdaptorException("Unable to construct Adaptor " +
              adaptorClass + " instance for " +
              adaptable.getClass());
        }
      }

      // Construct the new Adaptor instance
      try {
        if (constructorArgClass == null) {
          adaptor = (Adaptor)adaptorConstructor.newInstance();
        } else {
          adaptor = (Adaptor)adaptorConstructor.newInstance(adaptable);
        }
      } catch (RuntimeException re) {
        throw re;
      } catch (Exception e) {
        throw new AdaptorException("Unable to create kind Adaptor", e);
      }

      // Save the adaptable
      adaptable.addAdaptor(adaptor);
    }
    return adaptor;
  }
}