[brailleblaster] Re: Draft of BrailleBlaster Architecture: FOR FEEDBACK

Michael,

This sounds good. I agree that it is probably best to let you do the 
building and maintenance of Maven. What do I need to install to use 
Maven onn a Linux CentOS system? Where can I find a tutorial on Maven?

John B.

On Wed, Jul 28, 2010 at 10:00:37PM +0100, Michael Whapples wrote:
> Maven should be able to handle native code, there are plugins like the 
> native plugin for maven 
> http://mojo.codehaus.org/maven-native/native-maven-plugin/. I've not 
> worked out all of the stuff to do with including native code but I get 
> the feeling what we would need would be possible.
> 
> As for supporting maven, I have said I am prepared to maintain that as a 
> build system for us, that would include assisting people in using maven 
> to perform the tasks. I am not sure whether I would want to go fully to 
> the level of supporting people with editing the pom file, it may be much 
> simpler for requests for alterations to be made and for me to make the 
> alteration.
> 
> As for whether maven has a steep learning curve, not sure if that's so. 
> I feel possibly for those just building/testing/etc a project using 
> maven it can be much simpler. For those who need to edit the pom file, 
> you just need to get in the frame of mind of maven, if you don't then it 
> may be hard going. Maven you are configuring to behave as you want 
> rather than telling it the steps it must do.
> 
> Michael Whapples
> On 28/07/10 18:38, John J. Boyer wrote:
> >Michael,
> >
> >Maven is supposed to have a steep learning curve. Are you willing to
> >help the rest of us learn it?
> >
> >How would Mavenn handle dependencies such as liblouis and liblouisutdml?
> >The latter, inn its turn, has a dependency on libxml2. Right now,
> >itex2MML has a small main C program. I want to make it into a shared or
> >dynameic library. That won't be difficult. I think hunspell is already
> >a
> >library. We also will develop something to interface with MathType if
> >the user installs it. Can MathType be used as a library? Where do we get
> >the API? So Maven will have to cope with a lot of dependencies, not just
> >jar files.
> >
> >John B.
> >
> >On Wed, Jul 28, 2010 at 06:12:41PM +0100, Michael Whapples wrote:
> >   
> >>Hello,
> >>I agree with most of that. The one thing I may dispute, but its most
> >>likely to circumstances, I have suggested maven because that is what I
> >>have become familiar with, I did try ant but found the explicit step by
> >>step nature of it so verbose that it was a bit much, and as nobody has
> >>come forward offering to maintain an ant build system it just seems more
> >>logical for me to suggest maven.
> >>
> >>Out of curiosity, how does slf4j or log4j compare to the logging API in
> >>the JDK? I have used the logging API included in the JDK before but
> >>never log4j. Which ever logging system is used, I too strongly say a
> >>logging system should be used.
> >>
> >>It was interesting to see your comment on jdom and dom4j, the choice of
> >>dom4j was based on it being a dependency for tika so using dom4j would
> >>keep the dependencies down.
> >>
> >>Junit, certainly that should be used and used correctly (I am of the
> >>view of test driven development, even if it doesn't quite always happen
> >>in practice). Maven integrates junit well with the build process (IE.
> >>when you build maven will also test).
> >>
> >>Michael Whapples
> >>On 28/07/10 15:31, Chris von See wrote:
> >>     
> >>>Maven (http://maven.apache.org/) and other dependency management
> >>>systems such as Ivy (http://ant.apache.org/ivy/) are great for
> >>>tracking and managing dependencies during the development process, and
> >>>once set up they can really facilitate integration of third-party
> >>>libraries into a development environment.  Having said that, Apache
> >>>Ant is a very nice build tool for Java projects, and while it doesn't
> >>>have the dependency management capabilities of Maven it can be easily
> >>>be set up to build and package projects.  Eclipse and other IDEs have
> >>>built-in support for generating Ant build files.  You should use
> >>>whichever build system works for you - BrailleBlaster doesn't sound
> >>>like it's going to be such a large project that Ant will be
> >>>unworkable, and since the Maven learning curve is very steep you may
> >>>find Ant to be more to your liking.
> >>>
> >>>I agree with the various comments about not putting JAR files in the
> >>>source path - they should go into a "lib" directory or (in the case of
> >>>Maven) into the local Maven repository.  An Eclipse-generated Ant
> >>>build file will include a classpath which is based on the Eclipse
> >>>project configuration; if you use Maven then the classpath will be
> >>>built for you automatically as well as long as you've defined your
> >>>dependencies in the POM file.
> >>>
> >>>I haven't really read the BrailleBlaster spec or your proposed project
> >>>structure in depth, but I do have a few other suggestions:
> >>>
> >>>-- Consider using JUnit (http://www.junit.org) to write your unit
> >>>tests.  JUnit will integrate with Maven to automatically run your
> >>>tests during the project build process.
> >>>-- If you'll have a lot of developers in different locations doing
> >>>development, I recommend implementing a central file server with a
> >>>continuous integration server such as Hudson (http://hudson-ci.org/)
> >>>or Bamboo (http://www.atlassian.com/software/bamboo/).  Atlassian has
> >>>a very nice hosted environment called Jira Studio
> >>>(http://www.atlassian.com/hosted/studio/) that includes Subversion,
> >>>Bamboo,  Confluence (Wiki), Crucible (peer code review), and Jira
> >>>(issue tracking), but it does cost money... you may be able to find
> >>>other similar hosted environments out there that are free.
> >>>-- Definitely take some time to look through the Apache Commons
> >>>libraries (http://commons.apache.org) - there are libraries there that
> >>>can help you quickly build several portions of BrailleBlaster,
> >>>including the command line (Commons CLI package), config files
> >>>(Commons Configuration), XML-to-object mapping (Commons Digester), and
> >>>many, many other pieces.  The Commons IO and Commons Lang packages are
> >>>particularly useful.
> >>>-- Use SLF4J (http://www.slf4j.org/) or Log4J
> >>>(http://logging.apache.org/log4j/1.2/) for your logging support.
> >>>-- Take a look at using JDOM (http://www.jdom.org/) instead of DOM4J -
> >>>personally, I find JDOM to be easier to use.
> >>>-- Look at using Apache POI (http://poi.apache.org/) instead of or in
> >>>addition to Tika for file import.  POI uses Tika for some file formats.
> >>>
> >>>Feel free to send me any questions you may have.  I don't have much
> >>>time during the day, but I'll try to respond as quickly as possible.
> >>>
> >>>
> >>>
> >>>Chris von See
> >>>Senior Geek
> >>>TechAdapt, Inc.
> >>>http://www.techadapt.com
> >>>chris@xxxxxxxxxxxxx
> >>>
> >>>Save trees.  Print only when necessary.
> >>>
> >>>
> >>>
> >>>
> >>>
> >>>On Jul 28, 2010, at 5:53 AM, Michael Whapples wrote:
> >>>
> >>>       
> >>>>On 28/07/10 10:22, John J. Boyer wrote:
> >>>>         
> >>>>>Thanks. So the jar files will go in a lib directory, and all the src
> >>>>>files will go in a src directory. I have already received a similar
> >>>>>suggestion offlist. I would rather not make BrailleBlaster dependent on
> >>>>>maven or on any particular IDE, though it should work with them.
> >>>>>           
> >>>><MW>What a suggestion, you don't want to depend on maven, I guess in
> >>>>the same way liblouis doesn't depend on GNU make. What I am getting
> >>>>at is we do want a build system, I understand how maven works and
> >>>>have suggested I could maintain the build process if we were to use
> >>>>maven. There are other build tools for java, ant is a popular choice
> >>>>but I am not willing to undertake the task of maintaining an ant
> >>>>build system. Is anyone else coming forward to offer to support
> >>>>another build system?</MW>
> >>>>
> >>>>         
> >>>>>Where
> >>>>>should bindings and small C programs which may be necessary go?
> >>>>><MW>As bindings tend to be jar files (at least for the part java
> >>>>>accesses) then lib seems a good choice. As for C programs,depends
> >>>>>what you mean, C source code which is part of brailleblaster
> >>>>>probably would want to live in src somewhere (maven actually has
> >>>>>subdirectories of src, one for java code and one for resources, you
> >>>>>might be able to have a c subdirectory as well). External libraries
> >>>>>may want to live in lib or you may have a separate lib like folder
> >>>>>for shared libraries (may be jar files go in jar and native
> >>>>>libraries in lib). If its an executable then may be you want a bin
> >>>>>directory.</MW>
> >>>>>
> >>>>>           
> >>>><MW>There are a few other things I want to comment on which possibly
> >>>>deal more with the actual architecture, but those to another
> >>>>message.</MW>
> >>>>
> >>>>
> >>>>         
> >>>>>John B.
> >>>>>
> >>>>>On Wed, Jul 28, 2010 at 09:59:26AM +0100, Michael Whapples wrote:
> >>>>>
> >>>>>           
> >>>>>>As I classify some of the issues as fundamental, I feel continuing to
> >>>>>>work as described would really be digging yourself a hole. Proper
> >>>>>>discussion is meant to mean that we clear up the fundamental issues, I
> >>>>>>only have a few minutes now so will give full details in a later
> >>>>>>message. I am sorry but you will just have to take my word here
> >>>>>>until I
> >>>>>>can be more detailed.
> >>>>>>
> >>>>>>To attend to the jar file question. If we use maven then all external
> >>>>>>dependencies are handled for us, all the external jar files are
> >>>>>>located
> >>>>>>in our local maven repository (maven gets them if we don't have them).
> >>>>>>If we weren't using maven then the correct positioning of dependencies
> >>>>>>might be a lib directory, the lib directory should be separate from
> >>>>>>the
> >>>>>>source tree (IE. all source files are in packages with src as their
> >>>>>>base
> >>>>>>directory).
> >>>>>>
> >>>>>>When we distribute a binary version of BrailleBlaster then we have
> >>>>>>a few
> >>>>>>choices: Try and bundle everything in one jar file, this may be
> >>>>>>difficult to do for something as complicated as BrailleBlaster and may
> >>>>>>not offer the flexibility we may desire. Create a zip file containing
> >>>>>>everything and handy scripts to start BrailleBlaster (IE. the scripts
> >>>>>>manage getting the classpath and other java things correct), in which
> >>>>>>case the jar files may be in a lib directory. This second option is
> >>>>>>more
> >>>>>>flexible as it would allow multiple scripts for launching different
> >>>>>>tools (my detailed message will discuss why this may be desirable).
> >>>>>>
> >>>>>>Michael Whapples
> >>>>>>On 28/07/10 09:03, John J. Boyer wrote:
> >>>>>>
> >>>>>>             
> >>>>>>>Michael,
> >>>>>>>
> >>>>>>>I don't think extensive discussion of this matter is needed. Where do
> >>>>>>>you suggest putting the jar files? What other issues do you see? Both
> >>>>>>>the specification and the architecture are works in progress.
> >>>>>>>
> >>>>>>>John B.
> >>>>>>>
> >>>>>>>On Wed, Jul 28, 2010 at 01:28:07AM +0100, Michael Whapples wrote:
> >>>>>>>
> >>>>>>>
> >>>>>>>               
> >>>>>>>>Hello,
> >>>>>>>>I don't have much time this evening to go into detail on this, but I
> >>>>>>>>have noticed some matters which are basic problems and should not be
> >>>>>>>>done in Java. One really obvious one (not the only one) is the
> >>>>>>>>suggestion of putting .jar files in a package, you just don't do
> >>>>>>>>that it
> >>>>>>>>breaks the concept of Java. In short its breaking things because any
> >>>>>>>>given package may be put in a jar file and a jar file is just a
> >>>>>>>>handy
> >>>>>>>>collection of packages bundled into one file. Putting jar files in a
> >>>>>>>>package simply means you are putting packages inside a package (this
> >>>>>>>>does not lead to a subpackage, the jar file gets in the way). To
> >>>>>>>>make
> >>>>>>>>that work you end up having a classpath pointing into a package,
> >>>>>>>>this
> >>>>>>>>causes issues when packing the outer package into a jar file.
> >>>>>>>>
> >>>>>>>>As there's some really basic and fundamental issues here I
> >>>>>>>>suggest no
> >>>>>>>>progress until its discussed properly. I hope to be able to do that
> >>>>>>>>either tomorrow or Thursday.
> >>>>>>>>
> >>>>>>>>Michael Whapples
> >>>>>>>>On 27/07/10 21:22, John J. Boyer wrote:
> >>>>>>>>
> >>>>>>>>
> >>>>>>>>                 
> >>>>>>>>>Here is a draft of the architecture of BrailleBlaster and of the
> >>>>>>>>>Java
> >>>>>>>>>directory tree that incorporates it. This is very preliminary,
> >>>>>>>>>since I
> >>>>>>>>>am quite new to Java. It also assumes that you are familiar with
> >>>>>>>>>the
> >>>>>>>>>BrailleBlaster specification on the BrailleBlaster project page at
> >>>>>>>>>http://code.google.com/p/brailleblaster The project page for
> >>>>>>>>>liblouisutdml is at http://code.google.com/p/liblouisutdml and the
> >>>>>>>>>project page for liblouis is at http://code.google.com/p/liblouis
> >>>>>>>>>
> >>>>>>>>>The main method, in a class called BbMain, will first read a
> >>>>>>>>>file giving
> >>>>>>>>>user preferences (format described later). It will accept
> >>>>>>>>>arguments. If
> >>>>>>>>>these arguments indicate that only a translation is required, for
> >>>>>>>>>example if they specify only an input and output file, the main
> >>>>>>>>>method
> >>>>>>>>>will use methods in the FileImport class to transform the input
> >>>>>>>>>file, if
> >>>>>>>>>necessary, then call liblouisutdml to make the translation and
> >>>>>>>>>produce
> >>>>>>>>>the output file, then exit. In this case it will not use any GUI
> >>>>>>>>>components. This means that it can be called from a command line
> >>>>>>>>>or used
> >>>>>>>>>as part of a script. If there are no arguments or if they do not
> >>>>>>>>>indicate a simple translation the main method will call the Welcome
> >>>>>>>>>method in the class BbWelcome unless the user's preferences
> >>>>>>>>>indicate
> >>>>>>>>>that she does not want to see the welcome screen or use any of its
> >>>>>>>>>features but wants to go directly to the editor. In this case or
> >>>>>>>>>when
> >>>>>>>>>the Welcome method has concluded its work, the editor method in the
> >>>>>>>>>class BbEditor will be invoked. This class will be one of a
> >>>>>>>>>considerable
> >>>>>>>>>number in the package org.brailleblaster.editor which accomplish
> >>>>>>>>>various
> >>>>>>>>>editing and display tasks. When the user has finished her work the
> >>>>>>>>>Editor method returns to the main method, which does cleanup and
> >>>>>>>>>exits.
> >>>>>>>>>
> >>>>>>>>>In accordance with Java conventions, the package names also
> >>>>>>>>>indicate the
> >>>>>>>>>structure of the directory tree.  The package names in the
> >>>>>>>>>BrailleBlaster application will begin with org.brailleblaster
> >>>>>>>>>
> >>>>>>>>>One package will be org.brailleblaster.External which will
> >>>>>>>>>contain the
> >>>>>>>>>bindings for libllouisutdml and liblouis. It will also contain the
> >>>>>>>>>bindings for itex2MML and hunspell, together with any small C
> >>>>>>>>>programs
> >>>>>>>>>needed to implement native mothods. The programs for the
> >>>>>>>>>bindings will
> >>>>>>>>>be external shared libraries. The bindings for MathType will
> >>>>>>>>>also be
> >>>>>>>>>here. If MathType is not installed and the user tries to use it,
> >>>>>>>>>she
> >>>>>>>>>will of course get an error message.
> >>>>>>>>>
> >>>>>>>>>Another package will be org.brailleblaster.Base which will
> >>>>>>>>>contain the
> >>>>>>>>>class BbMain and a number of .jar files for things that have been
> >>>>>>>>>developed elsewhere. It will also contain the class FileImport
> >>>>>>>>>which
> >>>>>>>>>will use the methods in tika and may have methods for file types
> >>>>>>>>>that
> >>>>>>>>>tika does not support, such as Duxbury and MegaDots.
> >>>>>>>>>
> >>>>>>>>>Another package will be org.brailleblaster.Welcome which will
> >>>>>>>>>contain
> >>>>>>>>>mostly the class BbWelcome.
> >>>>>>>>>
> >>>>>>>>>Most of the code will be in org.brailleblaster.Editor This will
> >>>>>>>>>contain
> >>>>>>>>>a number of subpackages, such as
> >>>>>>>>>org.brailleblaster.editor.EditMain and
> >>>>>>>>>org.brailleblaster.editor.BrailleWindow and
> >>>>>>>>>org.brailleblaster.editor.TextWindow It may also contain .jar
> >>>>>>>>>files, and
> >>>>>>>>>it will call classees in other packages, such as FileImport. The
> >>>>>>>>>editor
> >>>>>>>>>will be based on SWT and dom4j. It will call liblouisutdml for
> >>>>>>>>>braille
> >>>>>>>>>translations and will use functions in liblouis to assist with
> >>>>>>>>>displaying braille on the screen.
> >>>>>>>>>
> >>>>>>>>>The format of the user preferences file is of some concern. A
> >>>>>>>>>default
> >>>>>>>>>file will be supplied with BrailleBlaster. This can be changed
> >>>>>>>>>in the
> >>>>>>>>>welcome screen and the editor. The file will be named something
> >>>>>>>>>like
> >>>>>>>>>preferences.xml Its root element will be<preferences>     It will
> >>>>>>>>>contain
> >>>>>>>>>various subtrees, such as<usage>  <formatting>  <translation>     
> >>>>>>>>>and
> >>>>>>>>><printing>     Each of these divisions will contain<meta>
> >>>>>>>>>elements with
> >>>>>>>>>attributes of the form name="xxx" content="yyy" The<usage>
> >>>>>>>>>section, for
> >>>>>>>>>example, will contain<meta name="welcome" content="no"/>
> >>>>>>>>>dom4j will be
> >>>>>>>>>used to read and parse this file as necessary and to make
> >>>>>>>>>changes in it.
> >>>>>>>>>
> >>>>>>>>>As stated at the beginning, this is very preliminary, and it is
> >>>>>>>>>written
> >>>>>>>>>by someone who is by no means a Java expert. Feedback is needed to
> >>>>>>>>>refine it. Thanks.
> >>>>>>>>>
> >>>>>>>>>John B.
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>                   
> >>>>>>>>
> >>>>>>>>                 
> >>>>>>>
> >>>>>>>               
> >>>>>>             
> >>>>>           
> >>>>
> >>>>         
> >>>
> >>>       
> >>     
> >   
> 

-- 
John J. Boyer; President, Chief Software Developer
Abilitiessoft, Inc.
http://www.abilitiessoft.com
Madison, Wisconsin USA
Developing software for people with disabilities

Other related posts: