Directions for use of 4A Annotation Server

• Installing
  • Latest NetBeans plugins
• Server interfaces
  • Interface for 4A clients
  • Web based user interface for users and administrators
    • Testing interface
    • Documents
    • Users
    • User groups
    • Types of annotations
    • Upload ontology
    • Attributes From Ontology
    • Batch Rename and Comment Types of annotations and its attributes
  • Other server interfaces
• Code documentation

1. Download and install NetBeans 7.0 to 7.3 All with GlassFish server 3.x
2. Download and install MySQL database server
3. Download 4A Annotation server from GIT repository http://knot.fit.vutbr.cz/annotations/server/Annotations.git/
4. Put downloaded server to your NetBeans projects directory (eg. ~/NetBeansProjects/ or c:\Documents and Settings\Administrator\Dokumenty\NetBeansProjects\) and open this project in NetBeans
5. Before running server, Comet support must be enabled in GlassFish (in NetBeans click on Services tab in left panel -> Servers -> click to GlassFish by right mouse button -> Properties -> Enable comet support).
6. To successfully start server on first attempt, you must copy Annotations/lib/Jena-2.6.4/lib/xercesImpl-2.7.1.jar to domain libraries directory in your GlassFish (eg. ~/glassfish-3.0.1/glassfish/domains/domain1/lib/). If you don't do that, server starts only each second attempt or randomly. If it crashes, you must stop GlassFish and run project again.
7. For smooth function of 4A server administration interface, you must install the new version of the JavaFaces - copy (with rename and replace) Annotations/resources/JavaFaces/javax.faces-2.1.13.jar to modules directory in your GlassFish (eg. ~/glassfish-3.0.1/glassfish/modules/javax.faces.jar or if you have newer version of GlassFish ~/glassfish-3.1.2.2/glassfish/modules/java-faces.jar).
8. Increase memory limits in ~/glassfish-3.0.1/glassfish/domains/domain1/config/domain.xml
   

           <jvm-options>-XX:MaxPermSize=4096m</jvm-options>
           <jvm-options>-XX:PermSize=2048m</jvm-options>
           <jvm-options>-Xmx4096m</jvm-options>
     
     WARNING: There are two instances of each row above!!!
   

9. Create database according to informations in Annotations/setup/sun-resources.xml or modify this file according to created database.
10. Execute SQL statements from Annotations/resources/db/annotations.sql (almost empty database - you must log in to web interface and set up for annotating first) or from Annotations/resources/db/annotations_min_data.sql (minimal data for start testing with clients immediately).
11. In /Annotations/src/java/cz/vutbr/fit/knot/annotations/app/Constants.java change SERVER_URI according to intended usage (it must exactly match with address set in the client - so client can not have knot.fit.vutbr.cz if SERVER_URI is localhost).
12. If you do not like to use our public semantic enrichment server, you can download the SEC API from GIT repository http://knot.fit.vutbr.cz/sec/secapi.git/ and put it to /var/sec. Download knowledge base and automatas using downloadKB.sh in the directory /var/sec/NER. Then run make in directory /var/sec/SEC_API and try to run ./sec_api.py. If it will fail, install dependencies (python packages), run make in subdirectories with Makefile etc. Running SEC API can be tested by test_sec.py.
13. Build and run server.
14. Log in to the administration interface to initialize it (first log in is very slow - it can take minutes if SEC API is starting for the first time).

There is a problem with the latest updates of NetBeans plugins, after installing these updates you can't start 4A Server. I found that the problem is a newer version of the JSF that lacks some of the methods used in 4A Server. Here is solution of this problem (Basically we will install an older version of JSF):

1. Switch the view of the Project in NetBeans.
2. Find "Libraries" folder and "JSF 2.2" library in it.
3. Remove "JSF 2.2" from "Libraries" folder.
4. Right mouse button click on "Libraries" folder and clic on "Add Library".
5. In Add Library form click on "Create ..." button and type name of new library (for example "JSF 2.1") and confirm.
6. Now, select new library ("JSF 2.1" in my case) in "Avaible Libraries" menu and click on Add Library.
7. Thats all, now you can run 4A Server.

• Server have several interfaces. Two most important are:
  
  1. Interface for 4A clients
  2. Web based user interface for users and administrators

• If server is on localhost, clients communicates with server via http on address http://localhost:8080/Annotations/AnnotEditorsComet
• Details of communication protocol v. 1.1 are described in 4A Framework - Protocol and Annotation Format Specification.
• Details of communication protocol v. 2.0 are described in 4A Framework version 2 - Protocol and Annotation Format Specification (also available in czech).

• Testing interface accomplish you simulate the 4A client. It's intended mainly for client developers.
• You can write XML with request, send to server and observe the response.
• You can also set the session id and number of retries (avoid infinite loop), start the comet polling (asynchronous channel from server to clients) and observe messages from server.

• You can use very simple document storage on the server and share your documents with other users.
• Documents are accessible to all users (because they can join to any group), but they are assigned to groups for lucidity. You can filter and see only documents in selected groups or documents owned by selected users (lists on the bottom of page).
• It's intended for annotating documents, which you have only on localhost before, because no other user can see this documents and their annotations, if you have them only on localhost. Furthermore, on the server annotations are assigned to documents by its URI so if you move documents to another place on localhost, you can't see the annotations.
• For adding of new document you can use "Insert new" link under the table. Then you select a file and fill in user group to which document will be assigned.
• For annotating the document you can open it in a new tab or window and use 4A Annotation extension for your web browser. Link for opening the document is placed under the file name.

• This page is intended for administration of users.
• For new user you must specify login, password and full name. Optionally e-mail can be introduced.
• If you set or change the password, hash function will be used and only hash stored in the database.
• After you save the new user, server unique URI will be assigned to him and you can join him to user groups (in editation of user).
• If user created some annotations, you can't delete them without deleting of annotations, but you can change his password, so he is not able to log in.

• This page is intended for administration of user groups.
• For new user group you must specify it's name.
• After you save the new user group, server unique URI will be assigned to it and you can add users to this user group (in editation of user group).
• Group "Administrators" can't be deleted and the last user can't be removed from this group (because only administrator can add new administrators and if nobody is administrator, nobody can create new one).

• On this page you can manage types of annotations.
• On the bottom of page there is a list for selecting of user groups which types will be displayed in the treetable.
• For new type you must specify its name, primary ancestor and user group in which will be shared. Optionally you can fill in comment which can be showed to users to clarify meaning of type. URI in ontology is also optional and is intended for use with tree of types imported from ontology.
• Type can have restricted attributes. If it have restriction enabled, user can't add new attributes to type. It's necessary to note, that in current version of server and client it's not fully implemented, so restriction is not enforced (will be fixed in one of next versions).
• Only alphabetical characters, numbers and some other characters as "-" (dash), "_" (underline) and "." (dot) are allowed in type name in actual version of system. If multiple words are necessary, they must be delimited by dot or underline, not by space character. For names of attributes it's the same, but space character can be used.
• In editation of type you can also manage template for attributes and ancestors of type. It's important, that primary ancestor is specifying path in the tree and linearized name of type. If you change primary ancestor, all subtypes will be changed too. All other ancestors are only specifying alternative ways to find this type for user and may clarifying meaning of type.
• For new attribute you must fill in name and simple type or linearized name of type of annotation (can be selected from the tree after clicking to button). Optionally comment for clarifying and URI in ontology can be filled too. If attribute will be marked as required, users will be forced to fill it's value (or to modify attribute and uncheck the required checkbox).
• If you make any change in types, connected clients will not be notified in current version of server! It will be implemented in next version.

• You can upload ontology in RDF/XML file and import it to types of annotations. Classes will be transformed to types of annotations and relations will be transformed to attributes. Many of informations will be discarded (anonymous classes, values of literals and many of others), but all informations necessary for annotating will be imported.
• Before import you must specify user group to which types will be imported and what to do, if some of imported types are already stored in database. Current version of server don't support use existing types as ancestors or attributes of imported types, but if ontology is updated, you can import it again two ways. One way is to preserve old type, if exists (add new types only), second way is to update type (use new attributes, ancestors etc.).
• Attributes where haven't domain set will be stored separately and in the near future clients can offer them to user in dialog for adding of attribute.

• On this page you can manage attributes imported from ontology, which was not domain set (it is not clear in which types can be used).

• On this page you can upload file with informations for batch renaming and commenting of types of annotations and its attributes.
• It is intended for use with upload of ontology (you can upload ontology from some author and then apply own changes to it on all servers what you manage).
• Here is an example of file for batch renaming: batchRename.xml

• Get document servlet allows to get server's current copy of annotated document. For usage simply send request for appropriate URI to the server with parameter "id" containing id of the document on the server (eg. http://localhost:8080/Annotations/documents/getDoc?id=1).
• Get stored document servlet allows to get stored document from the simple document storage on the server. Example of URI is http://localhost:8080/Annotations/getDocument?id=1
• Get annotation servlet allows to get annotations stored on the server. Example of request URI is http://localhost:8080/Annotations/GetAnnot?out=v2&doc=1 Parameters of URI allows to specify output format ("out=v1" for 4A annotation format, "out=v2" for Open Annotation or "out=sug" for SXML) and some detailed setting for given format (eg. withCreated for SXML). It is possible to get all annotations for given user (eg. "user=1" or "user=idytrych") and/or document (eg. "doc=1" or "docUri=http%3A%2F%2Fwww.example.com%2Fdocument.txt"). It is also possible to get annotation with given uri ("?uri=...").
• Document clone servlet allows to create clone of the document with all associated annotations. It is intended as an API for content management system so we will not document it here - see documentation of the sources.

• Architecture:
  
• Code documentation (generated) can be found here. It is updated rarely on the web server so we recommend to generate it from sources in repository using Doxygen.