Android中文API（144） —— JsonWriter

前言

　　本章內容android.util.JsonWriter章節，版本為Android 4.0 r1，翻譯來自："yddido"。

  

JsonWriter

譯者署名：yddido

譯者鏈接：http://blog.csdn.net/yddido

版本：Android 4.0 r1

 

結構

繼承關系

public final class JSonWriter extends Object implements Closeable 

        

java.lang.Object

android.util.JsonWriter

                  

類概述

輸出JSON（RFC4627）的流編碼值，每次一個token。這個流值包括文字內容（字符串，數字布爾值，nulls）以及對象和數組的開始和結束符。

 

JSON編碼

         將數據編碼為JSON格式，創建一個JsonWriter對象。每個JSON文件必須包含一個頂層的數組或者對象。嵌套數組和對象必須如下調用方法來組織內容：

l   寫數組，首先要調用beginArray()。用適當的value()方法或嵌套其他數組和對象為每個元素賦值。最後關閉數組調用endArray()。

l   寫對象，首先調用beginObject()。通過交替調用name(String)方法循環寫入對象屬性值。用適當的value()方法或嵌套其他數組和對象寫入熟悉值。最後關閉對象調用endObject()。 

 

例子

編寫流信息如下：

 [

   {

     "id": 912345678901,

     "text": "How do I write JSON on Android?",

     "geo": null,

     "user": {

       "name": "android_newb",

       "followers_count": 41

     

   },

   {

     "id": 912345678902,

     "text": "@android_newb just use android.util.JsonWriter!",

     "geo": [50.454722, -104.606667],

     "user": {

       "name": "jesse",

       "followers_count": 2

     }

   }

 ]}

如下表示以上信息結構：

   public void writeJsonStream(OutputStream out, List messages) throws IOException {
      JsonWriter writer = new JsonWriter(new OutputStreamWriter(out, "UTF-8"));
      writer.setIndent("  ");
      writeMessagesArray(writer, messages);
      writer.close();
    
 
    public void writeMessagesArray(JsonWriter writer, List messages) throws IOException {
      writer.beginArray();
      for (Message message : messages) {
        writeMessage(writer, message);
      }
      writer.endArray();
    }
 
    public void writeMessage(JsonWriter writer, Message message) throws IOException {
      writer.beginObject();
      writer.name("id").value(message.getId());
      writer.name("text").value(message.getText());
      if (message.getGeo() != null) {
        writer.name("geo");
        writeDoublesArray(writer, message.getGeo());
      } else {
        writer.name("geo").nullValue();
      }
      writer.name("user");
      writeUser(writer, message.getUser());
      writer.endObject();
    }
 
    public void writeUser(JsonWriter writer, User user) throws IOException {
      writer.beginObject();
      writer.name("name").value(user.getName());
      writer.name("followers_count").value(user.getFollowersCount());
      writer.endObject();
    }
 
    public void writeDoublesArray(JsonWriter writer, List doubles) throws IOException {
      writer.beginArray();
      for (Double value : doubles) {
        writer.value(value);
      }
      writer.endArray();
    }}

JsonWriter可用於來寫一個JSON流。這個類的實例不是線程安全的。調用JsonWriter產生一個不規則JSON字符串會拋出異常IllegalStateException。

 

構造方法

    public JsonWriter (Writer out)

         創建一個新的JSON編碼流的實例。為了獲得最佳性能，需要確保Write緩沖，必要時強制轉換為BufferedWriter。

 

公共方法

public JsonWriter beginArray()

開始一個新的數組編碼。每次調用這個方法必須調用一個endArray()進行配對。

         返回值

                   JsonWriter對象。

         異常

                   IOException

 

public JsonWriter beginObject()

開始一個新的對象編碼。每次調用這個方法必須調用一個endObject ()進行配對。

         返回值

                   JsonWriter對象。

         異常

                   IOException

 

public void close()

刷新和關閉實例對象和底層Writer。

         異常

                   IOException     如果JSON文件不完整拋出此異常。

 

public JsonWriter endArray()

        結束當前編碼數組

         返回值

                   JsonWriter對象。

         異常

                   IOException

 

public JsonWriter endObject()

結束當前編碼對象

         返回值

                   JsonWriter對象。

         異常

                   IOException

 

public void flush()

確保所有緩存數據寫入底層Writer並刷新(flush)這個實例對象。

 

public boolean isLenient()

如果writer對象是不嚴格的語法規則返回true。

 

public JsonWriter name(String name)

編碼屬性名

         參數

                   name        將被賦值對象的名字，不允許使用空值。

         返回值

                   JsonWriter對象。

         異常

                   IOException

 

public JsonWriter nullValue()

編碼空值。

         返回值

                   對象本身。

         異常

                   IOException

 

public void setIndent(String indent)

為編碼文檔每一級設置縮進字符串。如果indent.isEmpty()返回true編碼文檔將被壓縮，否則編碼文檔將更加易讀。

         參數

                   indent       一個僅包含空格的字符串。

 

public void setLenient(boolean lenient)

配置writer對象使其使用不嚴格的語法規則。默認情況下，此writer對象只能發送符合RFC 4627語法規則的JSON。設置允許writer不嚴格規則如下：

l   最頂層的值可以是任何類型。嚴格來說，最頂層的值必須是一個對象或者數組。

l   數字可以是非數值類型或無限大。

 

public JsonWriter value(double value)

編碼屬性值

參數

         Value       一個限定的值。不能是非數值或無限大的數(NaNs)，除非writer對象是不嚴格的。

返回值

         Writer對象

異常

         IOException

        

public JsonWriter value(long value)

編碼屬性值

返回值

         Writer對象

異常

         IOException

 

public JsonWriter value(Number value)

編碼屬性值

參數

         Value       一個限定的值。不能是非數值或無限大的數(NaNs)，除非writer對象是不嚴格的。

返回值

         Writer對象

異常

         IOException

 

public JsonWriter value(boolean value)

編碼屬性值

返回值

         Writer對象

異常

         IOException

 

public JsonWriter value(String value)

編碼屬性值

參數

         Value       一個字符串值，或者空值來編碼空字符

返回值

         Writer對象

異常

         IOException