Dynamic UNOIDL Reference Browser

From Apache OpenOffice Wiki
Jump to: navigation, search

The Dynamic UNOIDL Reference Browser has been accepted as a Google Summer of Code project 2006 out the project ideas. This project page keeps you informed about the ongoing work on this project.

Student 
Lin Rongheng (ronghenglin at gmail.com)
Mentor 
Juergen Schmidt (juergen.schmidt at sun.com)


Abstract

The OpenOffice.org API is specified in UNOIDL (UNO Interface Definition Language). UNOIDL allows a language independent description of the API and language bindings/bridges allows the use of the same API from various languages where exactly such a language binding/bridge exists. But often it is difficult for users of the API to map the language independent UNOIDL reference documentation to their preferred and used programming language, e.g. Java or StarBasic. But exactly this would speed up their daily work, a Java programmer would like to have a Javadoc like reference of the API. The idea of a “Dynamic UNOIDL Reference Browser” is to develop a new concept for documenting IDL types in XML and a concept to provide a dynamically created representation for different languages.
That means in detail that the reference browser would dynamically create a piece of XML code from the IDL definition and the provided XML documentation string for the IDL type. An appropriate XSL transformation would convert the XML representation into the required language representation. For example a Java developer gets the correct Java mapping for an IDL interface type.
The dynamically approach has the advantage that we can (in a second step) analyze the navigation path to a type and can show context specific documentation. That can be very useful for generic types which have different meanings in different contexts. For example a return type of a generic type XEnumeration from function F of interface X. The generated documentation for XEnumeration would show exactly the info which is necessary to understand and use XEnumeration in the context of function F from interface X. It shows for example that the enumeration in this context always contains objects of type Y and even more information for more complex context dependent information.


Plan

There are several steps planned for this project:

  1. Setup a XML schema for UNOIDL type descriptions including type info and documents.
    MileStone : June 21. A XML schema setuped (done!)
  2. Define the output format for Java (Some javadoc like documentation) and provide XSLT to transform from XML to "the output format" dynamically
    MileStone : July 15. The transform is tested. (done!)
  3. Provide some GUI interface for a dynamic UNOIDL reference browser, containing a xhtml/html viewer and support of referenced types.
    MileStone : July 31. A GUI interface provided.(done! )
  4. Dynamical creation of UNOIDL XML files based on a UNO type library.
    MileStone : August 20. Finishing the dynamical reation.(done!)

Currently work

  1. Setup the environment for the openoffice UNO library using a Sun Java Studio Enterprise 8.(done!)
  2. write/run some type library demos to have a clear view about the UNOIDL types.(done!)
  3. Think about how to connect the UNOIDL types to the Schema.
    some understanding of the UNOTYPE (updated 2006-6-1 9:56 (GMT+8)) (done!)
  4. Give some schema demo for simple type.
    An alpha sample example of schema (updated 2006-6-1 14:00 (GMT+8)) (done!)
  5. Give a more detail schema for the UNOIDL types.
    more detail schema (updated 2006-6-12 14:40 (GMT+8)) (done!)
  6. Add the support of Module and Constant.A new version is being setuped. The version will add the support of the module and constant. Also , in the new version, I would separate the type into two kind: a "ref-type" and a "raw-type"(means the type define itself). I will post the new version in my blog as soon as possible. After the version , I would begin to test the xml files generated by the schema. And then, after fully tested, the schema part would be finished. (updated 2006-6-13 13:40 GMT+8)# The new doc representation test. (first version of doc representation has begun. in this version, i test the xml to the xhtml and think about how to make the xhtml nice  :) soon I will link the page (updated 2006-6-14 23:36 GMT+8))
  7. I have some mis-understanding of the UNOIDL, so I have to change some UNOIDL type defines, such as "typeDef","Struct","Constant".(updated 2006-6-16 12:22 GMT+8)(done!)
  8. A new version of schema released . (updated 2006-6-16 13:40 GMT+8)
    Some new features
  9. A simple sample XSLT for the XML. ( a ugly doc represenation has been setuped, but it is so ugly... :( and the xslt is very simple, just finish the "interface" type. more will come soon )(updated 2006-6-19 13:44 GMT+8)
  10. A simple demo doc-representation for the transformation has been setuped. The demo is almost the same as java-doc. ( updated 2006-6-20 20:00 GMT+8)
  11. the additional java helper class is added. The class is to help the tranformation easier. (updated 2006 2006-06-21 9:00 GMT+8) (done!)
  12. A new doc-representation is setuped, together with the xslt file. :)
    a java-doc like represenation(updated 2006-06-21 21:49 GMT+8)
    yet another view
  13. The "Struct","Service","Enum","Module" doc-represenations are aslo setuped ! (updated 2006-06-22 14:54 GMT+8)
  14. All types doc-represenations are setuped. (updated 2006-06-27 13:00 GMT+8)
  15. The schema will be redefined, using relaxng.
    a tutorial of relaxng
  16. I will on a business travel to ChongQing. I will learn relaxng on the travel. And a redefined version may be setuped during the weekend. (updated 2006-06-27 17:00 GMT+8)
  17. Back from Chongqing.
  18. a relaxng based schema is setuped and being tested. :) (updated 2006-07-03 13:21 GMT+8)
  19. A new doc-representation based relaxng schema are setuped and tested (updated 2006-07-04 17:00 GMT+8)
  20. yet another schema is setuped based on the advice of mentor (updated 2006-07-06 16:40 GMT+8)
    yet another version of schema
  21. A fully review of the schema and the xslt. :) (updated 2006-07-07 12:12 GMT+8)
  22. A picture of the browser is setuped.refer to a first version picture(updated 2006-07-11 14:33 GMT+8)
  23. some ideas about the idl browser. We may use a opensource engine for the html rendering or write by ourselves. There are some opensource engine(eg, JRex,X-Smiles,etc...)(updated 2006-07-11 14:36 GMT+8)
  24. a demo idl browser ui is setuped. And the demo viewer is also setuped.
    the first version of demo idl browser(updated 2006-07-13 14:11 GMT+8)
  25. a idl browser with type browser supported are setuped. a new version support type browser(updated 2006-07-19 17:23 GMT+8)
  26. test the xslt for the mapping of java type.. ( processing ) (updated 2006-07-24 12:29 GMT+8)
  27. a not full test of xslt using the binary library of Ooo. (updated 2006-07-27 15:10 GMT+8)
  28. a full test of xslt using the binary library of Ooo. Besides, the openoffice version is updated to 2.0 (updated 2006-07-30 16:20 GMT+8)
  29. a simple idea of the auto generating doc-representation from a binary library
  30. a doc is released for the idea . (updated 2006-08-01 16:00 GMT+8)
  31. begin to write some code upon the idea (updated 2006-08-03 17:38 GMT+8)
  32. write the XML generating part's code (updated 2006-08-09 17:30 GMT+8)
  33. write the Html generating part's code and test the generating, aslo test the xslt with the generating (updated 2006-08-11 16:00 GMT+8)
  34. write the thread-pool and the message queue for the background generating.(updated 2006-08-13 15:34 GMT+8)
  35. begin to integart the code with GUI. (updated 2006-08-14 GMT+8)
  36. send mentor a version with basic function. (updated 2006-08-16 GMT+8)
    some picture of this version.
    the main frame
    change the condition
    some other operations
    some other operations
  37. test and fix some bugs.
  38. Juergen changes the start up mode. Using the uno bootstrap feature, and rename the project DynamicReferenceBrowser.Now the startup of the app is simplier,easier. :) (updated 2006-08-24 19:08 GMT+8)

Summary of the project

In the front, I want to thank Juergen. As we know, he is very busy, but he is very kind. He always give me many useful ideas and point out my faults. When I have any question, whether the question is stupid or not, he always give me the response as soon as possible. Also when I have some ideas, he is very respectful of my idea; gives me a free way to deal with the project. So it is a very happy time to do this project with Juergen. As he said, we are a team.
This project is to help the developers easier to access the UNOIDL type doc-representation, no matter what languages they use. As the description of the project abstract in the openoffice wiki, we finally achieve the goals.

  1. Define a UNOIDL schema And generating the XML files. Use both W3C and Relaxng to define a schema. This schema can describe the UNOIDL. Also use some XML files to verify the schema. And finally, it shows the schema is ready for the description of the UNOIDL type.
  2. Define the XSLT files. Currently, we define the XSLT for Java. The XSLT can transform the XML files to correct HTML representation. Of course, current representation is a java-do like representation. So it is simply for the java developer to use.
  3. Design the GUI. The GUI includes two major parts, the type browser and the html viewer. The type browser can browser the type of UNOIDL type. And the html viewer is to show the HTML files. And they all work fine.
  4. The dynamic generating of the type and dynamic showing. Generate the type’s correct supporting files (the XML/HTML files). Then use the html viewer to show the file. In this part, we consider of the context generating and the background caching. That means, when we generate a file, we also consider the type that are contained in the file. So when people click the type on the type browser, the html viewer will show the correct doc-representation

So using this browser, we can access the doc of UNOIDL type. And we only need to supply binary library file, then we can generate the doc-representation that we need. It would be very useful for developers to use.
But still there is something open for people to extend the project. As we know, the doc can’t be extracted from current version binary library of Ooo. So in that case, we have to extend current library’s interface. When the binary library finally supports the doc extracted. This project can extract the doc from the binary library. Meanwhile, current version’s browser only supports the Java language, so when we need to support other language, we only need to define the new style XSLT files. Then the new language will be supported by the browser. The browser can be also used as a simple xml generating tool or an html generating tool, people can use it as a library to develop other application.
When I do this project, I learn some from it. It is the first time that I join in the open source community to do a project. So I finally know how the open source project organizes, and how the people work on it. Everyday, when I read the mail-list, I would find some question in it, and then the discussion, and then the final agreement. Though, I haven’t published any question on it, but I can feel that it is a active team.Additional, I learn some other knowledge. Such as, the UNOIDL, the XSLT, XML, the openoffice library, etc… The openoffice’s architecture gives me some more ideas in my research field. It makes my view broader when I do other things. I have considered to use the openoffice related API in the telecom NGN SCE (Service creation environment) design.
As a whole, it is a very happy time to do this project. And I have learned some from this project. In the later days, I will continue to do some work for the open source. I think it would also be a proud thing.

Code

The code for this project is available in cvs under http://api.openoffice.org/source/browse/api/dynamicreferencebrowser/.
You can also use "anoncvs" (see Downloading the Source Code from CVS) to checkout the whole project "/api/dynamicreferencebrowser". The easiest way is to checkout the project directly from NetBeans because the project is a Netbeans project and will be opened directly after the checkout. The project can be easy compiled and run from within NetBeans. Read the "How_to_use.txt" text file in the project root to get info about how you can adapt the project to your environment.

Requirements

Using NetBeans to checkout the project

NetBeans supports CVS and offers a nice integration in the IDE. To checkout the project

  1. Start NetBeans
  2. Choose CVS -> Checkout
  3. Specify the CVs root: ":pserver:anoncvs@cvs.netbeans.org:/cvs"
  4. Specifiy the password: "anoncvs"
  5. Click next and select the module/project: "api/dynamicreferencebrowser"
  6. Let the branch field empty to checkout the top level version
  7. Specify the destination folder and click finish to start the checkout
  8. Confirm the open project dialog to open the project in NetBeans

How to use it

1) how to setup the program.
(before you setup the program, make sure the JVM is installed.And the Openoffice or StartOffice has been installed.)
a, use a netbeans.
b, choose File--from the existed project, located the project dir(which you get from the SVN or other places)
c, setup a library called StarOffice8. The library includes these files:ridl.jar,unoil.jar,juh.jar,jurt.jar,jut.jar,officebean.jar,java_uno.jar,unloader.jar
(Note: the files can be found in the %Ooo%/program/classes)

2) how to run the program
a, simply run the class: org.openoffice.develop.DynamicReferenceBrowser

Some work after Summer of Code

  1. continue to check if the schema is ok.
  2. make sure the transform is OK.
  3. auto generating some index in the html representation.


A Personal Blog

Bios Space may be updated everyday, Including some other interesting things that happened around.

Retrieved from "https://wiki.openoffice.org/w/index.php?title=Dynamic_UNOIDL_Reference_Browser&oldid=157943"
Personal tools