smart-exim/smart-exim-api/src/main/java/com/smartitengineering/exim/Importer.java

   1 /*
   2  * This is a common dao with basic CRUD operations and is not limited to any
   3  * persistent layer implementation
   4  *
   5  * Copyright (C) 2008  Imran M Yousuf (imyousuf@smartitengineering.com)
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 3 of the License, or (at your option) any later version.
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  18  */
  19 package com.smartitengineering.exim;
  20
  21 import java.io.IOException;
  22 import java.io.InputStream;
  23 import java.lang.annotation.Annotation;
  24 import java.lang.reflect.Type;
  25 import java.util.List;
  26 import java.util.Map;
  27
  28 /**
  29  * This API provides SPIs to use it to import objects from stream of media type
  30  * it specifies. It is the responsibility of the API client to invoke it for
  31  * appropriate {@link MediaType}. API implementors should explicitly mention the
  32  * media type it supports. API implementors should also ensure thread safety.
  33  * @author imyousuf
  34  * @since 0.4
  35  */
  36 public interface Importer {
  37
  38     /**
  39      * An operation that checks whether the the object type qualified by its
  40      * class is supported by this importer. This operation should be consulted
  41      * before invoking/using importObject.
  42      * @param clazz The class quantifying the object type
  43      * @param genericType The generic applied to the object, if any
  44      * @param annotations Annotations used on the class
  45      * @return True if and only if import is supported else false.
  46      */
  47     boolean isImportSupported(Class clazz,
  48                               Type genericType,
  49                               Annotation[] annotations);
  50
  51     /**
  52      * Import the object quantified by clazz and genericType and qualified by
  53      * the annotaitons from the inpuStream and use the headers to retrieve meta
  54      * informations regarding the object.
  55      * @param clazz The class of the object
  56      * @param genericType The generic used with the object.
  57      * @param annotations Annotations qualifying the object's class.
  58      * @param inputStream The input stream to read and parse the object from.
  59      * @param headers The headers that holds the meta information
  60      * @return The object formed by from the input stream. Should never be NULL.
  61      * @throws java.io.IOException If any error in reading from the stream, i.e.
  62      *                             either format error or any other error.
  63      */
  64     Object importObject(Class clazz,
  65                         Type genericType,
  66                         Annotation[] annotations,
  67                         InputStream inputStream,
  68                         Map<Object, List<Object>> headers)
  69         throws IOException;
  70
  71     /**
  72      * Provides the {@link MediaType} that is supported by this importer.
  73      * @return The supported media type
  74      */
  75     String getMediaType();
  76 }