misc/env/src/main/java/org/onap/aaf/misc/env/Data.java

   1 /**\r
   2  * ============LICENSE_START====================================================\r
   3  * org.onap.aaf\r
   4  * ===========================================================================\r
   5  * Copyright (c) 2018 AT&T Intellectual Property. All rights reserved.\r
   6  * ===========================================================================\r
   7  * Licensed under the Apache License, Version 2.0 (the "License");\r
   8  * you may not use this file except in compliance with the License.\r
   9  * You may obtain a copy of the License at\r
  10  * \r
  11  *      http://www.apache.org/licenses/LICENSE-2.0\r
  12  * \r
  13  * Unless required by applicable law or agreed to in writing, software\r
  14  * distributed under the License is distributed on an "AS IS" BASIS,\r
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  16  * See the License for the specific language governing permissions and\r
  17  * limitations under the License.\r
  18  * ============LICENSE_END====================================================\r
  19  *\r
  20  */\r
  21 \r
  22 package org.onap.aaf.misc.env;\r
  23 \r
  24 import java.io.IOException;\r
  25 import java.io.InputStream;\r
  26 import java.io.OutputStream;\r
  27 import java.io.Reader;\r
  28 import java.io.Writer;\r
  29 /**\r
  30  * <H1>Data</H1>\r
  31  * <i>Data</i> facilitates lazy marshaling of data with a pre-determined\r
  32  * marshaling mechanism.<p>\r
  33  * \r
  34  * It stores either Object (defined by Generic {@literal <T>}) or String.<p>  \r
  35  * \r
  36  * On asking for Object of type {@literal <T>}, it will respond with the object\r
  37  * if it exists, or unmarshal the string and pass the result back.<p>\r
  38  * \r
  39  * On asking for String, it will respond with the String\r
  40  * if it exists, or marshal the String and pass the result back.<p>\r
  41  *\r
  42  * the "options" available on several functions control the output of this particular call.  When \r
  43  * blank, they will default to the DataFactory defaults.  When present, they override this\r
  44  * particular call.\r
  45  *      The available options are "pretty" (for XML and JSON) and "fragment" (XML only concept), which drops\r
  46  * the "<?xml ...?>" header so you can create larger XML documents from the output. \r
  47  * \r
  48  * @author Jonathan\r
  49  *\r
  50  * @param <T>\r
  51  */\r
  52 public interface Data<T> {\r
  53         static enum TYPE {XML,JSON,JAXB,RAW,DEFAULT};\r
  54         // can & with 0xFFFF;\r
  55 //      public static final int XML = 0x1;\r
  56 //      public static final int JSON = 0x2;\r
  57 //      public static final int JAXB = 0x4;\r
  58 //      public static final int RAW = 0x1000;\r
  59         \r
  60         // can & with 0xF00000;\r
  61         public static final int PRETTY = 0x100000;\r
  62         public static final int FRAGMENT = 0x200000;\r
  63 \r
  64         /**\r
  65          * Respond with the String if it exists, or marshal the String and pass the result back.\r
  66          * \r
  67          * However, use the Env the Data Object was created with.\r
  68          * \r
  69          * @return String\r
  70          * @throws APIException\r
  71          */\r
  72         public String asString() throws APIException;\r
  73 \r
  74         /**\r
  75          * Respond with the Object of type {@literal <T>} if it exists, or unmarshal from String \r
  76          * and pass the result back.<p>\r
  77          *\r
  78          * However, use the Env the Data Object was created with.\r
  79          * \r
  80          * @return T\r
  81          * @throws APIException\r
  82          */\r
  83         public T asObject() throws APIException;\r
  84 \r
  85         /**\r
  86          * Set a particular option on an existing Out \r
  87          * \r
  88          * if int is negative, it should remove the option\r
  89          * @param option\r
  90          */\r
  91         public Data<T> option(int option);\r
  92 \r
  93         public Data<T> to(OutputStream os) throws APIException, IOException;\r
  94         public Data<T> to(Writer writer) throws APIException, IOException;\r
  95         \r
  96         public Data<T> load(T t) throws APIException;\r
  97         public Data<T> load(String str) throws APIException;\r
  98         public Data<T> load(InputStream is) throws APIException;\r
  99         public Data<T> load(Reader rdr) throws APIException;\r
 100         \r
 101         public Data<T> in(TYPE type);\r
 102         public Data<T> out(TYPE type);\r
 103         /**\r
 104          * Return the Class Type supported by this DataObject\r
 105          * \r
 106          * @return {@literal Class<T>}\r
 107          */\r
 108         public Class<T> getTypeClass();\r
 109 \r
 110         public void direct(InputStream input, OutputStream output) throws APIException, IOException;\r
 111 \r
 112 \r
 113 }