Public:BWmeta service/Java mapping

From YaddaWiki

< Public:BWmeta service(Difference between revisions)
Jump to: navigation, search
(→Contracts)
 
(13 intermediate revisions not shown)
Line 11: Line 11:
| Repo model || 1.0.0 ÷ 1.0.5 || [[Processes service|Processes]], [[YaddaWeb application|YaddaWeb]] ||  Hibernate-oriented
| Repo model || 1.0.0 ÷ 1.0.5 || [[Processes service|Processes]], [[YaddaWeb application|YaddaWeb]] ||  Hibernate-oriented
|-
|-
-
| DeskLight model || 1.0.0 ÷ 1.0.5 || [[DeskLight application|DeskLight]] ||
+
| DeskLight model || 1.0.0 ÷ 1.0.5 || [[Processes service|Processes]], [[DeskLight application|DeskLight]] ||
|-
|-
| "Y" model || 1.2.0 ÷ 2.0.0 || [[Pack Management service|Pack Management]] ||
| "Y" model || 1.2.0 ÷ 2.0.0 || [[Pack Management service|Pack Management]] ||
Line 41: Line 41:
<!-- * Only the following property types are present: a primitive type, a String, another "Y" object, a List of Strings or "Y" objects. -->
<!-- * Only the following property types are present: a primitive type, a String, another "Y" object, a List of Strings or "Y" objects. -->
 +
 +
== Nulls and empty texts ==
 +
In general nulls are not acceptible in places where should be text(String, YRichtext). If such field is set to null value then empty string is set automatically. Nulls are not returned from this fileds. Only exceptions that exists in system when nulls value are accepted on string fields are:
 +
* Identity w contributorze
 +
* TODO: tu wpisujemy miejsca gdzie są nulle
== Rich text support ==
== Rich text support ==
-
Support for rich text, [[BWmeta format#Rich text support|introduced in BWmeta 2.0.0]] calls for changes in the "Y" model.
+
''See [[BWmeta service/Java mapping/Rich text]].''
-
 
+
-
=== Adding <code>YRichText</code> class ===
+
-
 
+
-
<code>YRichText</code> is mutable.
+
-
 
+
-
==== Constructors ====
+
-
* <code>YRichText(String)</code> – constructor from plain text.
+
-
* <code>YRichText(List<YRichText.Part>)</code> – constructor from list of trees.
+
-
 
+
-
==== Methods ====
+
-
* <code>String toText()</code> – returns a flattened text view of the rich text.  It's a concatenation of text contents of the tree list visited in the infix order.
+
-
* <code>List<YRichText.Part> toParts()</code> – returns a list of trees which represent the rich text.
+
-
 
+
-
=== Changes in classes with a <code>YRichText</code> property ===
+
-
 
+
-
<code>YRichText</code>-related methods (other than the ones below) which have been already added should be <code>@Deprecated</code> and subsequently removed.
+
-
 
+
-
==== <code>YName</code>, <code>YDescription</code> ====
+
-
* Every constructor from <code>String text</code> has a corresponding constructor from <code>YRichText text</code>.
+
-
* <code>String getText()</code> – returns flattened text.
+
-
* <code>YRichText getRichText()</code> – returns rich text.
+
-
* <code>T setText(String)</code> – sets plain text.
+
-
* <code>T setRichText(YRichText)</code> – sets rich text.
+
-
 
+
-
==== <code>YAttribute</code> ====
+
-
* Every constructor from <code>String value</code> has a corresponding constructor from <code>YRichText value</code>.
+
-
* <code>String getValue()</code> – returns plain text.
+
-
* <code>YRichText getRichValue()</code> – returns rich text.
+
-
* <code>YAttribute setValue(String)</code> – sets plain text.
+
-
* <code>YAttribute setRichValue(YRichText)</code> – sets rich text.
+
-
 
+
-
==== <code>YTagList</code> ====
+
-
* <code>List<String> getValues()</code> – returns unmodifiable, flattened text view of the list of tags.
+
-
* <code>List<YRichText> getRichValues()</code> – returns modifiable list of rich text tags.
+
-
* <code>YTagList setValues(Collection<String>)</code> – sets plain text values.
+
-
* <code>YTagList setRichValues(Collection<YRichText>)</code> – sets rich text values.
+
-
* <code>YTagList addValue(String)</code> – adds a plain text value.
+
-
* <code>YTagList addRichValue(YRichText)</code> – adds a rich text value.
+
-
 
+
-
=== Adding <code>RichTextSerialization</code> utility class ===
+
-
* <code>String toXmlFragment(YRichText)</code> – serializes a rich text to an XML fragment.
+
-
* <code>YRichText fromXmlFragment(String)</code> – deserializes a rich text from an XML fragment.
+
-
 
+
-
=== Contracts ===
+
-
* For any <code>String text != null</code> the following assert should pass:
+
-
yFoo.setText(text);
+
-
// ... potential serialization and deserialization ...
+
-
// ... conversion to "DL" model and back ...
+
-
// ... or all of the above in any order ...
+
-
assertEquals(text, yFoo.getText());
+
-
 
+
-
* For any <code>String text != null</code> the following assert should pass:
+
-
yFoo.setText(text);
+
-
// ... conversion to "DL" model ...
+
-
assertEquals(text, dFoo.getText());
+
-
 
+
-
* Example:
+
-
yName.setText("<nowiki><b xmlns="http://www.w3.org/1999/xhtml">1 &amp;lt; 2</b></nowiki>");
+
-
// ... conversion Y -> DL ...
+
-
assertEquals("<nowiki><b xmlns="http://www.w3.org/1999/xhtml">1 &amp;lt; 2</b></nowiki>", dName.getText());
+
-
// ... conversion DL -> Y ...
+
-
assertEquals("<nowiki><b xmlns="http://www.w3.org/1999/xhtml">1 &amp;lt; 2</b></nowiki>", yName.getText());
+
-
 
+
-
*Example
+
-
YrichText text=yFoo.getRichText();
+
-
// ... potential serialization and deserialization ...
+
-
// ... conversion to "DL" model and back ...
+
-
// .. no edition etc...
+
-
// ... or all of the above in any order ...
+
-
YrichText text1=yFoo.getRichText();
+
-
assertEquals(text, text1);
+
-
 
+
-
*Partticularly:
+
-
YrichText rtext=yFoo.getRichText();
+
-
String text=yFoo.getText();
+
-
yFoo.setText(text);
+
-
 
+
-
YrichText rtext1=yFoo.getRichText();
+
-
assertEquals(rtext, rtext1);
+
-
 
+
-
 
+
-
* What if:
+
-
yName.setText("1 &lt; 2")
+

Latest revision as of 16:06, 15 January 2013

Service details
NameBWmeta
Code location
(relative to SVN root)		projects/dir/bwmeta-core
Javadoc
Contact personJakub Jurkiewicz

Contents

History

Three different mappings of BWmeta to Java have been written in the project's lifetime. The following table summarizes the mappings.

Model Name Works with
BWmeta versions 		Usage areas Comments
Repo model 1.0.0 ÷ 1.0.5 Processes, YaddaWeb Hibernate-oriented
DeskLight model 1.0.0 ÷ 1.0.5 Processes, DeskLight
"Y" model 1.2.0 ÷ 2.0.0 Pack Management

Current efforts are focused on replacing the older models (Repo and DeskLight) with the latest one ("Y"). The remainder of this page and all the other pages on BWmeta usage in YADDA assume usage of the "Y" model.

General contracts

Unless explicitly stated in the documentation, every "Y" class has the following properties:

  • has a public default constructor.
  • every property is protected, but has a public getter and setter.
  • getters of String, YLanguage and List properties can never return null. Instead, an empty String, YLanguage.Undetermined or an empty List is returned, respectively.
  • for every List<T> property:
    • its getter returns a modifiable List<T>;
    • its getter returns the same reference all the time;
    • its setter accepts any Collection<T> (and copies the contents);
    • there's an adder (which returns this).
  • every setter and every list adder returns this, which allows chained setting, e.g.: 
new YElement()
    .setId("bwmeta1.element.foo")
    .addName(new YName().setText("Foo").setLanguage(YLanguage.English))
    .addDescription(new YDescription().setText("Lorem ipsum").setLanguage(YLanguage.Latin));

The folowing contracts are to be implemented/verified in the future:

  • hashCode() and equals() methods are based on the values of all the properties, i.e., two "Y" objects are equal iff they are of the same type and all their properties are equal.


Nulls and empty texts

In general nulls are not acceptible in places where should be text(String, YRichtext). If such field is set to null value then empty string is set automatically. Nulls are not returned from this fileds. Only exceptions that exists in system when nulls value are accepted on string fields are:

  • Identity w contributorze
  • TODO: tu wpisujemy miejsca gdzie są nulle

Rich text support

See BWmeta service/Java mapping/Rich text.

Retrieved from "https://wiki.yadda.icm.edu.pl/yadda/Public:BWmeta_service/Java_mapping"
Personal tools