1# ConfigFile as API 2 3The ConfigFile as API is a formal Treble interface describing schemas of 4configuration files used across system and vendor partitions. 5The Java APIs in the current.txt file are not Java APIs for apps. It's a proxy 6for the schema of a xml file used between the system and vendor partition. 7The xml files are only ever parsed by apps on the system partition. 8 9## Add Schema 10Add the schema (attribute, element or new complexType …) you want to add to the 11xsd file. 12 13#### before 14```xml 15<xs:element name="class"> 16 <xs:complexType> 17 <xs:sequence> 18 <xs:element name="student" type="xs:string"/> 19 </xs:sequence> 20 <xs:attribute name="name" type=”xs:string”/> 21 </xs:complexType> 22</xs:element> 23``` 24 25#### after 26```xml 27<xs:element name="class"> 28 <xs:complexType> 29 <xs:sequence> 30 <xs:element name="student" type="xs:string"/> 31 </xs:sequence> 32 <xs:attribute name="name" type=”xs:string”/> 33 <xs:attribute name="number" type="xs:int"/> 34 </xs:complexType> 35</xs:element> 36``` 37 38Then run "make {xsd_config module_name} .docs-update-current-api" or "make 39update-api" to update all the xsd_config modules. 40 41In the above example, two functions are added as below. 42* method public int getNumber(); 43* method public void setNumber(int); 44 45## Remove Schema 46To remove a tag, add an annotation tag with the name of "Deprecated" into the 47tag to be deleted. Partners are not allowed to create new vendor images using 48deprecated tags 49 50#### before 51```xml 52<xs:element name="class"> 53 <xs:complexType> 54 <xs:sequence> 55 <xs:element name="student" type="xs:string"/> 56 </xs:sequence> 57 <xs:attribute name="name" type=”xs:string”/> 58 </xs:complexType> 59</xs:element> 60``` 61 62#### after 63```xml 64<xs:element name="class"> 65 <xs:complexType> 66 <xs:sequence> 67 <xs:element name="student" type="xs:string"> 68 <annotation name=”Deprecated”/> 69 </xs:element> 70 </xs:sequence> 71 <xs:attribute name="name" type=”xs:string”/> 72 </xs:complexType> 73</xs:element> 74``` 75 76After adding “Deprecated” annotation, we need to update the api or schema just 77like when adding a tag. In the above example, a @Deprecate annotation is added. 78* method @Deprecated public java.util.List<java.lang.String> getStudent(); 79After 2 years we can delete the tag. When deleting, delete the tag in the xsd 80file and the api in last_current.txt, and update it. 81 82## Release Schema 83If there are any changes, we update last_current.txt and last_removed.txt before 84release by copying current.txt and removed.txt to last_current.txt and 85last_removed.txt. 86 87## Supported/Unsupported Tags 88Only the follow tags and attributes are allowed: 89 90#### Supported 91```xml 92"xsd:schema" [ 93] 94 95"xsd:element" [ 96 "xsd:name" { 97 values: any valid java name 98 } 99 "xsd:type" { 100 values: built-in data type, simpleType or complexType 101 }, 102 "xsd:ref" { 103 values: another element 104 }, 105 "xsd:minOccurs" { 106 values: [ 0, maxOccurs ] 107 }, 108 "xsd:maxOccurs" { 109 values: [ 1, unbounded ] 110 }, 111] 112 113"xsd:attribute" [ 114 "xsd:name" { 115 values: any valid java name 116 } 117 "xsd:type" { 118 values: built-in data type, simpleType or complexType 119 }, 120 "xsd:ref" { 121 values: another element 122 }, 123] 124 125"xsd:complexType" [ 126 "xsd:name" { 127 values: any valid java name 128 } 129] 130 131"xsd:complexContent" [ 132] 133 134"xsd:simpleContent" [ 135] 136 137"xsd:restriction": [ 138 "xsd:base" { 139 values: built-in data type 140 } 141] 142 143"xsd:extension": [ 144 "xsd:base" { 145 values: built-in data type, simpleType or complexType 146 } 147] 148 149"xsd:simpleType": [ 150 "xsd:name" { 151 values: any valid java name 152 } 153] 154 155"xsd:list": [ 156 "xsd:itemType" { 157 values: built-in data type, or simpleType 158 } 159] 160 161"xsd:union": [ 162 "xsd:memberTypes" { 163 values: built-in data type, or simpleType 164 } 165] 166 167"xsd:sequence": [ 168] 169 170"xsd:choice": [ 171] 172 173"xsd:all": [ 174] 175 176"xsd:enumeration": [ 177 "xsd:value" { 178 values: built-in data type 179 } 180] 181``` 182