Change analysis server protocol to omit empty lists when optional.

pkg/analysis_server/tool/spec/spec_input.html

Index: pkg/analysis_server/tool/spec/spec_input.html
diff --git a/pkg/analysis_server/tool/spec/spec_input.html b/pkg/analysis_server/tool/spec/spec_input.html
index 1140275a7bf4618d68a66de5e8e2e1ebb0e40197..6eaf3204e535280b6e565572a6968e18b9106036 100644
--- a/pkg/analysis_server/tool/spec/spec_input.html
+++ b/pkg/analysis_server/tool/spec/spec_input.html
@@ -35,9 +35,16 @@
       To ease interoperability with Lisp-based clients (which may not
       be able to easily distinguish between empty lists, empty maps,
       and null), client-to-server communication is allowed to replace
-      any instance of “<tt>{}</tt>” or “<tt>[]</tt>” with null. The
-      server will always properly represent empty lists as
-      “<tt>[]</tt>” and empty maps as “<tt>{}</tt>”.
+      any instance of “<tt>{}</tt>” or “<tt>[]</tt>” with null.
+    </p>
+    <p>
+      In addition, to conserve bytes, all object fields of type "List"
+      are optional; omitting such a field carries the same meaning as
+      sending an empty list.
+    </p>
+    <p>
+      Server-to-client communication will always omit empty lists, and
+      will always represent empty maps as <tt>{}</tt>.

[Brian Wilkerson, 2014/08/22 15:12:45]

Do we want to have the same convention for maps?

     </p>
     <h3>Communication Structure</h3>
     <p>
@@ -170,7 +177,7 @@
           subscriptions will remain unchanged.
         </p>
         <params>
-          <field name="subscriptions">
+          <field name="subscriptions" optional="true">
             <list><ref>ServerService</ref></list>
             <p>A list of the services being subscribed to.</p>
           </field>
@@ -283,7 +290,7 @@
           </field>
         </params>
         <result>
-          <field name="errors">
+          <field name="errors" optional="true">
             <list><ref>AnalysisError</ref></list>
             <p>
               The errors associated with the file.
@@ -315,11 +322,11 @@
           </field>
         </params>
         <result>
-          <field name="hovers">
+          <field name="hovers" optional="true">
             <list><ref>HoverInformation</ref></list>
             <p>
               The hover information associated with the
-              location. The list will be empty if no information
+              location. The list will be omitted if no information
               could be determined for the location. The list can
               contain multiple items if the file is being analyzed
               in multiple contexts in conflicting ways (such as a
@@ -367,14 +374,14 @@
           be used to resolve package: URI’s within the file.
         </p>
         <params>
-          <field name="included">
+          <field name="included" optional="true">
             <list><ref>FilePath</ref></list>
             <p>
               A list of the files and directories that should be
               analyzed.
             </p>
           </field>
-          <field name="excluded">
+          <field name="excluded" optional="true">
             <list><ref>FilePath</ref></list>
             <p>
               A list of the files and directories within the
@@ -410,7 +417,7 @@
           actual priority files.
         </p>
         <params>
-          <field name="files">
+          <field name="files" optional="true">
             <list><ref>FilePath</ref></list>
             <p>
               The files that are to be a priority for analysis.
@@ -531,7 +538,7 @@
               The file containing the errors.
             </p>
           </field>
-          <field name="errors">
+          <field name="errors" optional="true">
             <list><ref>AnalysisError</ref></list>
             <p>
               The errors contained in the file.
@@ -558,7 +565,7 @@
           notification.
         </p>
         <params>
-          <field name="files">
+          <field name="files" optional="true">
             <list><ref>FilePath</ref></list>
             <p>
               The files that are no longer being analyzed.
@@ -587,7 +594,7 @@
               The file containing the folding regions.
             </p>
           </field>
-          <field name="regions">
+          <field name="regions" optional="true">
             <list><ref>FoldingRegion</ref></list>
             <p>
               The folding regions contained in the file.
@@ -612,7 +619,7 @@
               The file containing the highlight regions.
             </p>
           </field>
-          <field name="regions">
+          <field name="regions" optional="true">
             <list><ref>HighlightRegion</ref></list>
             <p>
               The highlight regions contained in the file. Each
@@ -642,7 +649,7 @@
               The file containing the navigation regions.
             </p>
           </field>
-          <field name="regions">
+          <field name="regions" optional="true">
             <list><ref>NavigationRegion</ref></list>
             <p>
               The navigation regions contained in the file. Each
@@ -676,7 +683,7 @@
               The file in which the references occur.
             </p>
           </field>
-          <field name="occurrences">
+          <field name="occurrences" optional="true">
             <list><ref>Occurrences</ref></list>
             <p>
               The occurrences of references to elements within the
@@ -727,7 +734,7 @@
               The file with which the overrides are associated.
             </p>
           </field>
-          <field name="overrides">
+          <field name="overrides" optional="true">
             <list><ref>Override</ref></list>
             <p>
               The overrides associated with the file.
@@ -806,7 +813,7 @@
               number of characters in the existing identifier).
             </p>
           </field>
-          <field name="results">
+          <field name="results" optional="true">
             <list><ref>CompletionSuggestion</ref></list>
             <p>
               The completion suggestions being reported.  The
@@ -1030,7 +1037,7 @@
               The id associated with the search.
             </p>
           </field>
-          <field name="results">
+          <field name="results" optional="true">
             <list><ref>SearchResult</ref></list>
             <p>
               The search results being reported.
@@ -1082,7 +1089,7 @@
           </field>
         </params>
         <result>
-          <field name="assists">
+          <field name="assists" optional="true">
             <list><ref>SourceChange</ref></list>
             <p>
               The assists that are available at the given location.
@@ -1119,7 +1126,7 @@
           </field>
         </params>
         <result>
-          <field name="kinds">
+          <field name="kinds" optional="true">
             <list><ref>RefactoringKind</ref></list>
             <p>
               The kinds of refactorings that are valid for the given
@@ -1150,7 +1157,7 @@
           </field>
         </params>
         <result>
-          <field name="fixes">
+          <field name="fixes" optional="true">
             <list><ref>ErrorFixes</ref></list>
             <p>
               The fixes that are available for each of the analysis
@@ -1217,7 +1224,7 @@
           </field>
         </params>
         <result>
-          <field name="status">
+          <field name="status" optional="true">
             <list><ref>RefactoringProblem</ref></list>
             <p>
               The status of the refactoring. The array will be empty

[Brian Wilkerson, 2014/08/22 15:12:45]

"empty" --> "omitted"

@@ -1366,7 +1373,7 @@
           subscriptions will remain unchanged.
         </p>
         <params>
-          <field name="subscriptions">
+          <field name="subscriptions" optional="true">
             <list><ref>DebugService</ref></list>
             <p>
               A list of the services being subscribed to.
@@ -1385,7 +1392,7 @@
           list of services passed in a debug.setSubscriptions request.
         </p>
         <params>
-          <field name="executables">
+          <field name="executables" optional="true">
             <list><ref>ExecutableFile</ref></list>
             <p>
               A list of the files that are executable in the given
@@ -1585,7 +1592,7 @@
         </p>
         <object>
           <field name="type" value="change"><ref>String</ref></field>
-          <field name="edits">
+          <field name="edits" optional="true">
             <list><ref>SourceEdit</ref></list>
             <p>
               The edits to be applied to the file.
@@ -1915,7 +1922,7 @@
               The error with which the fixes are associated.
             </p>
           </field>
-          <field name="fixes">
+          <field name="fixes" optional="true">
             <list><ref>SourceChange</ref></list>
             <p>
               The fixes associated with the error.
@@ -2190,7 +2197,7 @@
           all occurrences of the name could be edited simultaneously.
         </p>
         <object>
-          <field name="positions">
+          <field name="positions" optional="true">
             <list><ref>Position</ref></list>
             <p>
               The positions of the regions that should be edited
@@ -2204,7 +2211,7 @@
               simultaneously.
             </p>
           </field>
-          <field name="suggestions">
+          <field name="suggestions" optional="true">
             <list><ref>LinkedEditSuggestion</ref></list>
             <p>
               Pre-computed suggestions for what every region might
@@ -2303,7 +2310,7 @@
               The length of the region from which the user can navigate.
             </p>
           </field>
-          <field name="targets">
+          <field name="targets" optional="true">
             <list><ref>Element</ref></list>
             <p>
               The elements to which the given region is bound. By
@@ -2325,7 +2332,7 @@
               The element that was referenced.
             </p>
           </field>
-          <field name="offsets">
+          <field name="offsets" optional="true">
             <list><ref>int</ref></list>
             <p>
               The offsets of the name of the referenced element within
@@ -2607,7 +2614,7 @@
               it would be marked as being a potential match.
             </p>
           </field>
-          <field name="path">
+          <field name="path" optional="true">
             <list><ref>Element</ref></list>
             <p>
               The elements that contain the result, starting with the
@@ -2687,14 +2694,14 @@
               A human-readable description of the change to be applied.
             </p>
           </field>
-          <field name="edits">
+          <field name="edits" optional="true">
             <list><ref>SourceFileEdit</ref></list>
             <p>
               A list of the edits used to effect the change, grouped by
               file.
             </p>
           </field>
-          <field name="linkedEditGroups">
+          <field name="linkedEditGroups" optional="true">
             <list><ref>LinkedEditGroup</ref></list>
             <p>
               A list of the linked editing groups used to customize
@@ -2763,7 +2770,7 @@
               The file containing the code to be modified.
             </p>
           </field>
-          <field name="edits">
+          <field name="edits" optional="true">
             <list><ref>SourceEdit</ref></list>
             <p>
               A list of the edits used to effect the change.
@@ -2809,7 +2816,7 @@
               represents the class Object.
             </p>
           </field>
-          <field name="interfaces">
+          <field name="interfaces" optional="true">
             <list><ref>int</ref></list>
             <p>
               The indexes of the items representing the interfaces
@@ -2817,7 +2824,7 @@
               there are no implemented interfaces.
             </p>
           </field>
-          <field name="mixins">
+          <field name="mixins" optional="true">
             <list><ref>int</ref></list>
             <p>
               The indexes of the items representing the mixins
@@ -2825,7 +2832,7 @@
               there are no classes mixed in to this class.
             </p>
           </field>
-          <field name="subclasses">
+          <field name="subclasses" optional="true">
             <list><ref>int</ref></list>
             <p>
               The indexes of the items representing the subtypes of
@@ -2880,20 +2887,20 @@
           complete expression (no partial expressions are allowed).
         </p>
         <feedback>
-          <field name="names">
+          <field name="names" optional="true">
             <list><ref>String</ref></list>
             <p>
               The proposed names for the local variable.
             </p>
           </field>
-          <field name="offsets">
+          <field name="offsets" optional="true">
             <list><ref>int</ref></list>
             <p>
               The offsets of the expressions that would be replaced by
               a reference to the variable.
             </p>
           </field>
-          <field name="lengths">
+          <field name="lengths" optional="true">
             <list><ref>int</ref></list>
             <p>
               The lengths of the expressions that would be replaced by
@@ -2955,7 +2962,7 @@
               The proposed return type for the method.
             </p>
           </field>
-          <field name="names">
+          <field name="names" optional="true">
             <list><ref>String</ref></list>
             <p>
               The proposed names for the method.
@@ -2967,7 +2974,7 @@
               True if a getter could be created rather than a method.
             </p>
           </field>
-          <field name="parameters">
+          <field name="parameters" optional="true">
             <list><ref>RefactoringMethodParameter</ref></list>
             <p>
               The proposed parameters for the method.
@@ -2979,14 +2986,14 @@
               The number of times the expression or statements occurs.
             </p>
           </field>
-          <field name="offsets">
+          <field name="offsets" optional="true">
             <list><ref>int</ref></list>
             <p>
               The offsets of the expressions or statements that would
               be replaced by an invocation of the method.
             </p>
           </field>
-          <field name="lengths">
+          <field name="lengths" optional="true">
             <list><ref>int</ref></list>
             <p>
               The lengths of the expressions or statements that would
@@ -3019,7 +3026,7 @@
               The name that the method should be given.
             </p>
           </field>
-          <field name="parameters">
+          <field name="parameters" optional="true">
             <list><ref>RefactoringMethodParameter</ref></list>
             <p>
               The parameters that should be defined for the method.