Northwestern University Information Technology
MorphAdorner Server, or MAServer for short, is an HTTP-based server which exposes selected MorphAdorner facilities over the World Wide Web.
|September 25, 2013.
The MorphAdorner Server source code and support files, along with an issue tracker, are available as a git repository on bitbucket.org at
If you downloaded the MAServer release from the git repository on bitbucket.org, please go to the section "Installing and building MAServer."
If you downloaded the ready-to-use maserver-1.0.0.zip file, proceed as follows. Expand the contents of the maserver-1.0.0.zip file into an empty directory. Make sure you retain the existing directory structure.
You must have the Java run-time environment installed on your machine to run MAServer. If you do not, go to the section "Installing and Building MAServer" for information on where to get a copy of the Java runtime. Once you have Java installed you can proceed with running MAServer.
To run MAServer standalone on Windows, type
at the command line of a console window.
On Unix-like systems, including Mac OS X, type
chmod 755 runmaserver
in a terminal window to set the shell script to execute. You only need to do this once. To run the server, type
By default MAServer listens on TCP port 8182. You can change this default port number in the batch file or shell script. Both the batch file and script request 4 gigabytes of memory to run.
MAServer requires at least 2.5 gigabytes of memory to run with 4 gigabytes preferred. For best results you should run MAServer on a 64-bit operating system with a 64-bit version of the Java run-time environment installed. Your system may require more memory than these minimums. In particular, Mac OS X may require at least 3.0 gigabytes of memory to run MAServer.
You can access the test web pages once MAServer finishes initialization, which can take a couple of minutes on a slow system. Open a web browser on the system on which you are running MAServer and enter the URL
You should see the main MAServer test page. If you changed the default TCP port for the server, replace 8182 in the URL with your modified port number.
|File or Directory
|Build settings you can modify.
|Apache Ant build file used to compile MAServer.
|Template for generating web.xml file.
|Web Application Descriptor Language HTML conversion.
|Settings for generating web.xml file.
|Data files used by server.
|Documentation for using the server.
|Apache Ivy dependencies definitions.
|Apache Ivy settings.
|Java library files used by MAServer. These are retrieved on demand during the build process using Apache Ivy.
|The MAServer license.
|MAServer modification history.
|Printable copy of this file in Windows text format (lines terminated by Ascii CR/LF).
|Unix shell command file to start server in standalone mode.
|Windows batch file to start server in standalone mode.
|MAServer source code.
|Test data files.
|Static web pages for testing MAServer facilities.
To rebuild the MAServer code, make sure you have installed recent working copies of Oracle's Java Development Kit and Apache Ant on your system. The Java development kits for Windows, Mac OS X, and Linux systems may be obtained from
Alternatively, OpenJDK may be obtained from
Move to the directory into which you unzipped the MAServer release (or into which you cloned a local copy of the Mercurial repository for MAServer).
Use a plain text editor to edit the "build.properties" file. You should provide values for the following three settings.
The "serverdata.dir" setting should be set to the MAServer data directory for a remote installation of MAServer. This can be a local directory on your desktop if you are running MAServer under a local copy of a servlet server. This value is used only by the Ant "copyserverdata" task. If you don't intend to use that task to copy the server data, you may leave "serverdata.dir" empty.
The "localServerURL" setting should be set to the base URL of your local MAServer installation. The default value of
is fine for out-of-the-box use when you run the server using runmaserver.bat/runmaserver .
The "remoteServerURL" setting should be set to the base URL of your remote installation of MAServer, if any. This is needed to run tests against that server. If you only intend to run the built-in server version of MAServer (using runmaserver.bat/runmaserver), you may leave this setting empty.
For example, if your server name is "myremotehost.com", you would enter something like:
If you intend to run MAServer under a local copy of a servlet server such as Tomcat or Jetty on your own desktop, you can set the remoteServerURL to point to your desktop. In this case the setting will be something like:
Once you have set the above three entries in build.properties appropriately, save the build.properties file with the updated values.
To run MAServer under a servlet server such as Tomcat, you must also modify the settings in the conf/web-xml.properties file. Open this file with a plain text editor, and provide values for the following settings.
The "datadirectory" settings specifies the location of the MAServer data files -as seen by the servlet server-. This may differ from the value you set for "serverdata.dir" in the build.properties file.
The "maxunadorneduploadfilesize" specifies the maximum file size in bytes of an unadorned TEI XML file which the server will accept as an upload. The default value is "5m" or 5 megabytes.
The "maxadorneduploadfilesize" specifies the maximum file size in bytes of an adorned TEI XML file which the server will accept as an upload. The default value is "50m" or 50 megabytes. The larger the file size limits provided, the more memory the server requires to process the files.
Save the conf/web-xml.proerties file with the updated values.
After you have set the values in the build.properties and conf/web-xml.properties files appropriately, open a console or terminal window, move to the base directory of the MAServer release, and type:
to build MAServer. If the build completes successfully, the maserver.jar and maserver.war files will be placed in the "dist" subdirectory.
You must use a Java compiler which is compatible with Java 1.6 or higher. MAserver has been successfully compiled and executed under Windows and Linux using the standard Oracle JDK 1.6 and 1.7 releases; under Linux using a recent release of OpenJDK 7; and under Mac OS X using a recent version of the standard MAC OS X Java compiler and run-time. Other Java compilers and run-times may not work.
to generate the javadoc (internal documentation) into subdirectory "javadoc".
to remove the effects of compilation. This does not remove the downloaded files in the lib subdirectory. To remove those as well, type
Once in a while, if you are having trouble compiling, you may need to clean your Ivy cache to make sure you have the correct library files. Type
to clean the Ivy cache.
To deploy MAServer in a servlet server such as Tomcat you need to do four things:
Copy the data directory to a location of your choosing.
Copy the entire data/ directory along with its subdirectories to a directory somewhere on your system. By default this directory is defined as /project/maserverdata . You should change this setting in the conf/web-xml.properties file by setting the value of the "datadirectory" property to the correct directory name on your server.
If the remote server data directory is mounted so that you can access it locally, you can type
to copy the data files to the remote directory you specified as the value of the "serverdata.dir" setting in the build.properties file.
The data directory you select, and all its subdirectories, must be readable by your chosen servlet server. The servlet server must also have permission to change to that directory while running.
Rebuild the maserver.war file.
Rebuild the maserver.war file by typing
in a console/terminal window. The updated maserver.war file is written to dist/maserver.war .
Install the rebuilt maserver.war file into your servlet server.
Different servlet servers have various methods for doing this. Consult the documentation for your particular servlet server for details.
For example, in Tomcat, you can copy the maserver.war file to the Tomcat "webapps" subdirectory. Make sure you have configured Tomcat to deploy WAR files automatically by setting the "autoDeploy" option to "true" in the Host container element. See
MAServer has been tested to work under both Tomcat (v7) and Jetty (v8).
Some servlet servers can "hot install" new web applications presented as a war file, so you may not have to restart your server. It's usually a good idea to restart the server anyway. You must restart the server if you stopped the server before installing the MAServer war file.
After you restart your servlet server, MAServer should become available within a couple of minutes under the application name "maserver". Open a web browser on the system on which you are running the server and navigate to the web page URL
Replace "servername" with the name of the system on which you installed MAServer, and replace "8080" with the TCP port number for accessing your servlet server. You should see the main MAServer services web page once MAServer initialization completes.
The MAServer release contains a small set of tests which may be used to test the server's operation. These are not intended to be comprehensive.
To run the tests, make sure you've provided values for the "remoteServerURL" and/or "localServerURL" settings in build.properties, as described above.
The run the tests against a local MAServer instance, start that instance, then open a console/terminal window and type:
To run the tests against a remote MAServer instamce, make sure the remote instance is running, and type:
Examine the output for error messages. Usually either all of the tests will run successfully, or all of them will fail (usually because the MAServer instance isn't started or is blocked by a firewall).
MAServer is licensed under the same NCSA style open source license as MorphAdorner. See the license.txt file for details of this license.
The maserver.pdf file in the doc/ directory contains minimal documentation. At present this consists of an Adobe acrobat PDF file of the web application description language (WADL) for each MAServer service in human-legible format. Better documentation is in preparation. When ready it will appear online as part of the main MorphAdorner documentation at
as well as in printable (PDF) format.
You may also access the WADL (web application description language) definitions for all the services using a web browser. Start the local version of the MAServer server using the runmaserver.bat (Windows) or runmaserver script (Unix and Mac OS X). Then open the following site in your web browser:
The WADL for an individual service can be retrieved using
and replacing "servicename" with the name of the MAServer service for which you want the documentation. For example, the WADL for the lemmatizer service can be retrieved with:
If your system provides the curl utility, you can retrieve the XML formatted WADL descriptions for all services using curl in a console/terminal window as follows:
You can retrieve the WADL XML for a particular service -- say the lemmatizer service -- as follows:
You can also retrieve the WADL descriptions from a remotely installed MAServer installation by replacing "localhost:8182" with the server name and server port of the remote server. Examples:
Replace "myremotehost.com" with the name (and optionally the port number) of your remote MAServer instance.
Please see Accessing the MorphAdorner Server programmatically for details on accessing the MorphAdorner Server facilties from programs.
|Announcements and News
|Announcements and news about changes to MorphAdorner
|Documentation for using MorphAdorner
|Downloading and installing the MorphAdorner client and server software
|Glossary of MorphAdorner terms
|Natural language processing references
|Licenses for MorphAdorner and Associated Software
|Online examples of MorphAdorner Server facilities.
|Slides from talks about MorphAdorner.
|Technical information for programmers using MorphAdorner
Academic Technologies and Research Services,
NU Library 2East, 1970 Campus Drive Evanston, IL 60208. |