Public:Bwmeta service/Tutorial
From YaddaWiki
| Service details | |
|---|---|
| Name | BWmeta |
| Code location (relative to SVN root) | projects/dir/bwmeta-core |
| Javadoc | |
| Contact person | Jakub Jurkiewicz |
This page describes how to create completly new bwmeta docuemnt using Y model. Docuemnt described in this example describes some article.
Contents |
Creation of document of basic YElement
After setting all libraries, getting all imports, let's first create the new Empty YElement.
YElement article = new YElement();
Elements are used for all bliographic objects - books, chapters, articles, journals etc...
This is equal to creating new empty bwmeta element in xml:
<element xmlns="http://yadda.icm.edu.pl/bwmeta-2.x.x.xsd"> </element>
While we don't specify verion of bwmeta we marked xsd with x.x - it could be now 2.0.0 or 2.1.0.
Id
When we got article let's assign id to it:
article.setId("bwmeta1.element.element-form-pubmed-0000"/*PBMID*/+"22222");
Ids should be unique. They should be recognized by regexp: [A-Za-z0-9_./:@\-]+ Current practices applying to id are described here. After this our xml would look like:
<element xmlns="http://yadda.icm.edu.pl/bwmeta-2.x.x.xsd" id="bwmeta1.element.element-form-pubmed-000022222"> </element>
Title
After setting id lets set title of article. For describing titles we use YName.
YName nam=new YName();
nam.setText("Tytuł artykułu");
nam.setLanguage(YLanguage.English);
nam.setType(YConstants.NM_CANONICAL);
// nam.setType(YConstants.NM_SUBTITLE);
article.addName(nam);
Name with type canonical for article is a main title. Additionally for article we could set sub and super title etc...
It would add to our element field name:
<element xmlns="http://yadda.icm.edu.pl/bwmeta-2.x.x.xsd" id="bwmeta1.element.element-form-pubmed-000022222"> <name lang="eng" type="canonical"> Tytuł artykułu </name> </element>
Keywords and Category
For defining keywords and setting unknown categorizations YTagList should be used.
YTagList slowaKluczoweMim=new YTagList();
slowaKluczoweMim.setType("slowa_kluczowe_mim");
slowaKluczoweMim.setType(YConstants.TG_KEYWORD);
// type slowa_kluczowe mim wouldn't be used while it is overwritten with keyword
slowaKluczoweMim.setLanguage(YLanguage.Polish);
slowaKluczoweMim.addValue("ala");
slowaKluczoweMim.setValues(null);
In XMl it would add element tags(from this point we would only show added element that should be child of element element):
<tags lang="pol" type="keyword">
<tag>ala</tag>
</tags>
For define categories we use category-ref.
article.addCategoryRef(new YCategoryRef(YConstants.EXT_CLASSIFICATION_MSC_2010, "67.23.+"));
In xml it looks like:
<category-ref classification="bwmeta1.category-class.MSC" code="67.23.+" />
There is a big question sometimes what to use - tag list or category ref. IN general category-refs should be used for categorization terms known in SYNAT system. While we identify them by codes, it is usually maeningless to put the code, that is not recognized in system. For all other types of categorization - and all tapes of keywords tag list should be used.
Author - Contributor
Now we describe contributor of the article:
YContributor aut1=new YContributor(YConstants.CR_AUTHOR, false);
aut1.addAffiliationRef("aff1");
Affiliation should be reference to some existing affiliation element inside this article.
aut1.setRole(YConstants.CR_AUTHOR);
Other roles of contributor are: translator, editor, ilustrator etc...
aut1.addName(new YName(YLanguage.Undetermined, "A.G. Drag",YConstants.NM_CANONICAL));
This should be the name in form that it apears on front page.
aut1.addName(new YName(YLanguage.Undetermined, "A. G.", YConstants.NM_FORENAMES));
aut1.addName(new YName(YLanguage.Undetermined, "Drag", YConstants.NM_SURNAME));
If author could be recognized by system - for eample if we can recognize other publications by same person, we could
aut1.setIdentity("bwmeta1.person.person-000001");
The above in xml is:
<contributor institution="false" role="author">
<affiliation-ref ref="aff1" />
<identity ref="bwmeta1.person.person-000001" />
<name lang="und" type="canonical">A.G. Drag</name>
<name lang="und" type="forenames">A. G.</name>
<name lang="und" type="surname">Drag</name>
</contributor>
Now lets define affiliation that contributor was referenced to.
YAffiliation aff=new YAffiliation("aff1", "Uniwersytet Rzeszowski");
article.addAffiliation(aff);
In xml this affiliation should be expressed:
<affiliation id="aff1">
<text>Uniwersytet Rzeszowski</text>
</affiliation>
Abstract and other descriptions
Following code shows how to add abstract and summary to article.
article.addDescription(new YDescription(YLanguage.English, "yadda yadda ", YConstants.DS_ABSTRACT));
article.addDescription(new YDescription(YLanguage.English, "yadda yadda ", YConstants.DS_SUMMARY));
And in XML:
<description lang="eng" type="abstract">yadda yadda</description> <description lang="eng" type="summary">yadda yadda</description>
Relations - citation, reply etc...
Below is shown method for adding citations.
YRelation rel=new YRelation();
rel.setType(YConstants.RL_REFERENCE_TO);
rel.setTarget(new YId(YConstants.EXT_SCHEME_YADDA, "bwmeta1.element.element-docelowy-rel1"));
rel.addAttribute(YConstants.AT_REFERENCE_TEXT, "text referencji 1");
article.addRelation(rel);
YID set in target hasn't to be YADDA id , it could be also doi , coden , etc... To express this in xml write:
<relation type="reference-to" id-scheme="bwmeta1.id-class.YADDA" id-value="bwmeta1.element.element-docelowy-rel1">
<attribute key="reference-text">
<value>text referencji 1</value>
</attribute>
</relation>
How to define that object is Article? And where it has appear?
Now definition of some strange element called structure. It is very important element. It defines hierarchy to which specified element belongs to. It also defines element level and element parents. Because element could be anything this place defines its nature. Our element is article and therfor ebelongs to hierarchy journal.
YStructure struct=new YStructure(YConstants.EXT_HIERARCHY_JOURNAL);
YAncestor anc=new YAncestor(YConstants.EXT_LEVEL_JOURNAL_JOURNAL);
In most cases other journal should be also in system so we could call its object by id ( its soft reference and is not checked). However in example we've commented it out.
// anc.setIdentity("bwmeta1.element.journal-issn-00000032324");
anc.addName(new YName(YLanguage.English,"Journal of bibliography learning",YConstants.NM_CANONICAL));
struct.addAncestor(anc);
YAncestor anc2=new YAncestor(YConstants.EXT_LEVEL_JOURNAL_YEAR);
// anc2.setIdentity("bwmeta1.element.year-00000032324-2000");
anc2.addName(new YName("2000"));
struct.addAncestor(anc2);
Current element informs about what is the level of the element, In it we specify position of elment in its purent, ie. pages on which article appears in a journal.
YCurrent current=new YCurrent(YConstants.EXT_LEVEL_JOURNAL_ARTICLE);
current.setPosition("p.1-20");
struct.setCurrent(current);
article.addStructure(struct);
This whole structure element in XML is:
<structure hierarchy="bwmeta1.hierarchy-class.hierarchy_Journal">
<ancestor level="bwmeta1.level.hierarchy_Journal_Journal">
<name lang="eng" type="canonical">Journal of bibliography learning</name>
</ancestor>
<ancestor level="bwmeta1.level.hierarchy_Journal_Year">
<name lang="und">2000</name>
</ancestor>
<current level="bwmeta1.level.hierarchy_Journal_Article" position="p.1-20" />
</structure>
Atribute
Here we use attribute for storing information about source of article. This source is some hint that could be used later for identification of journal in which appers article, then - we wouldn't fill in parent level in structure.
// jak zapisać alternatywnie dla potrzbe przyszłego przetwarzania
YAttribute st=new YAttribute("SOURCE", "JOU. B. LEARN.");
article.addAttribute(st);
And in XML:
<attribute key="SOURCE">
<value>JOU. B. LEARN.</value>
</attribute>
It is important to understand that attributes have very low semantic meaqning and thus should be avoided if tehre is possibility of expressing their content using ither fields.
Dates
Here is shown how to setup date. - there are various types of dates connected to article - publication, accepted ...
YDate dat=new YDate(YConstants.DT_PUBLISHED, 2000, 1, 12, "druga połowa XX wieku");
article.addDate(dat);
And in XMl:
<date type="published" day="12" month="1" year="2000">druga połowa XX wieku</date>
YPerson
While we defined identity of person - here is example of this person element. It is not a part of article, but they could be serialized together.
YPerson per=new YPerson();
per.setId("bwmeta1.person.person-000001");
per.addName(new YName(YLanguage.Undetermined, "Aleksandra Genofewa", YConstants.NM_FORENAMES));
per.addName(new YName(YLanguage.Undetermined, "Drag-Kowalska", YConstants.NM_SURNAME));
In Xml it is separate object:
<person id="bwmeta1.person.person-000001"> <name lang="und" type="forenames">Aleksandra Genofewa</name> <name lang="und" type="surname">Drag-Kowalska</name> </person>
Serialization
To serialize created objects we need to add them to a list:
ArrayList<YExportable> list=new ArrayList<YExportable>();
list.add(article);
And then get propare transformer:
MetadataWriter<YExportable> writer=MetadataTransformers.BTF.getWriter(BwmetaTransformerConstants.Y, BwmetaTransformerConstants.BWMETA_2_1);
String xml= writer.write(list);
In result on String xml there is xml document conaining all elements that were on list. In teh same way we serialize person object:
ArrayList<YExportable> list2=new ArrayList<YExportable>();
list2.add(per);
String xmlPerson= writer.write(list2);
Final XMLs
Serialized xmls are following:
<?xml version="1.0" encoding="UTF-8"?> <bwmeta xmlns="http://yadda.icm.edu.pl/bwmeta-2.1.0.xsd"> <element id="bwmeta1.element.element-form-pubmed-000022222"> <affiliation id="aff1"> <text>Uniwersytet Rzeszowski</text> </affiliation> <attribute key="SOURCE"> <value>JOU. B. LEARN.</value> </attribute> <category-ref classification="bwmeta1.category-class.MSC" code="67.23.+" /> <contributor institution="false" role="author"> <affiliation-ref ref="aff1" /> <identity ref="bwmeta1.person.person-000001" /> <name lang="und" type="canonical">A.G. Drag</name> <name lang="und" type="forenames">A. G.</name> <name lang="und" type="surname">Drag</name> </contributor> <date type="published" day="12" month="1" year="2000">druga połowa XX wieku</date> <description lang="eng" type="abstract">yadda yadda</description> <description lang="eng" type="summary">yadda yadda</description> <name lang="eng" type="canonical">Tytuł artykułu</name> <relation type="reference-to" id-scheme="bwmeta1.id-class.YADDA" id-value="bwmeta1.element.element-docelowy-rel1"> <attribute key="reference-text"> <value>text referencji 1</value> </attribute> </relation> <structure hierarchy="bwmeta1.hierarchy-class.hierarchy_Journal"> <ancestor level="bwmeta1.level.hierarchy_Journal_Journal"> <name lang="eng" type="canonical">Journal of bibliography learning</name> </ancestor> <ancestor level="bwmeta1.level.hierarchy_Journal_Year"> <name lang="und">2000</name> </ancestor> <current level="bwmeta1.level.hierarchy_Journal_Article" position="p.1-20" /> </structure> </element> </bwmeta>
and:
<?xml version="1.0" encoding="UTF-8"?> <bwmeta xmlns="http://yadda.icm.edu.pl/bwmeta-2.1.0.xsd"> <person id="bwmeta1.person.person-000001"> <name lang="und" type="forenames">Aleksandra Genofewa</name> <name lang="und" type="surname">Drag-Kowalska</name> </person> </bwmeta>
