smart-exim/smart-exim-api/src/main/java/com/smartitengineering/exim/Exporter.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.OutputStream;
  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 export objects to a 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 Exporter {
  37
  38     /**
  39      * An operation that checks whether the the object type qualified by its
  40      * class is supported by this exporter. This operation should be consulted
  41      * before invoking/using exportObject.
  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 export is supported else false.
  46      */
  47     boolean isExportSupported(Class clazz,
  48                               Type genericType,
  49                               Annotation[] annotations);
  50
  51     /**
  52      * It provides the operation to predict the length of the exported content.
  53      * @param object The object to export
  54      * @param clazz The class of the object
  55      * @param genericType The generic used with the object.
  56      * @param annotations Annotations qualifying the object's class.
  57      * @return -1 if length can not be predicted or else the actual length after
  58      *          export
  59      */
  60     long getAfterExportLength(Object object,
  61                               Class clazz,
  62                               Type genericType,
  63                               Annotation[] annotations);
  64
  65     /**
  66      * Export the object quantified by clazz and genericType and qualified by
  67      * the annotaitons to the outpuStream and use the headers to set meta
  68      * informations regarding the object.
  69      * @param object The object to export
  70      * @param clazz The class of the object
  71      * @param genericType The generic used with the object.
  72      * @param annotations Annotations qualifying the object's class.
  73      * @param outputStream The output stream to write and format the object to.
  74      * @param headers The headers that holds the meta information
  75      * @throws java.io.IOException If any error in writing to the stream, i.e.
  76      *                             either format error or any other error.
  77      */
  78     void exportObject(Object object,
  79                       Class clazz,
  80                       Type genericType,
  81                       Annotation[] annotations,
  82                       OutputStream outputStream,
  83                       Map<Object, List<Object>> headers)
  84         throws IOException;
  85
  86     /**
  87      * Provides the {@link MediaType} that is supported by this exporter.
  88      * @return The supported media type
  89      */
  90     String getMediaType();
  91 }