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      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 }