JSON
Persistence
noreferences
@@tooltip Umple feature for Json serialization and de-serialization 

@@description
<p>JSON as a data-interchange format widely used to save and load data in many contexts and languages. It can be used in transmitting over networks. and saving the state of the system persistently.</p>

<p>Umple provides a capability to generate a Json representation of instances of any Umple class, including the complete network of all associated (linked) objects, as well as to reload objects that have been saved. This currently only works with the Java generator for Umple.</p>

&nbsp;<br/>

<p>To generate functions for serializing and deserializing Json in Umple Java code, specify the suboption &quot;genJson&quot; using the command line or UmpleOnline. A suitable command line would be: <i>umple [FILENAME].ump -g Java -s genJson -c-</i> ... this will generated the needed functions and also compile the code.</p>

<p>When specifying the suboption genJson, all generated Java classes will have the following functions as part of their API:</p>

<ul>
<li><b>String toJson()</b>. This method  generates (serializes) a Json representation of a given object, and all objects connected to it by associations.</li>
<li><b>Object fromJson(String)</b> This is a static method that instantiates (deserialize) all the objects that had been saved using toJson.  Data stored that represents attributes and associations is restored.</li>
</ul>

<p>External tools such as <a target="Gson" href="https://github.com/google/gson">GSON</a> can also be used to serialize and deserialize object data, but these tools do not support circular references. An attempt to save data with circular references in GSON will result in the code crashing with an infinite recursion error. A circular reference occurs when one object points to a second object, and the second object points back (possibly indirectly) to the first. Circular references are inherent in the code generated by Umple bidirectional associations and allow very useful and efficient APIs to be present in generated Umple code. Umple&apos;s builtin Json generation handles these circular references in persisted Json data by attaching an umpleObjectID to each saved object. When the date is re-loaded into Umple, these umpleObjectID codes are used to ensure that the circular references are regenerated correctly.</p>

&nbsp;<br/>
<p><b>Examples</b>: These demonstrate how use toJson() and fromJson() to serialize and de-serialize Json.</p>
&nbsp;<br/>

@@example @@caption This example shows a simple class implementing JSON Serialization @@endcaption
@@source manualexamples/JsonPersistenceExamples1.ump
@@endexample

@@example @@caption This example shows a more sophisticated model implementing JSON serialization and deserialization; it generates and outputs the Json, then reloads it, then outputs it again. The results are the same, except for the UmpleObjectIDs. @@endcaption
@@source manualexamples/JsonPersistenceExamples2.ump
@@endexample