...

<target name="fresh_install"
        depends="init_installation,init_configs,install_code"
        description="Do a fresh install of the system, overwriting any data">

Postgres changes

Enable pgcrypto extension

In order to generate UUID identifiers in postgres an extension module is required.

• Start by installing the "pgcrypto" module
• Connect to the database using user postgres
• Run the following command: "CREATE EXTENSION pgcrypto;"
• The output of the command if successful is blank, so you can always try to run "SELECT gen_random_uuid();" which should return a result.

Database migration to service based api

Database migration occurs on tomcat start (handled by flyway). Both existing databases & new installation should work, although existing databases has not been tested as well as a new database. There COULD be issues where an integer/boolean columns have the NULL value, the old DatabaseManager had a fallback to -1, false. Hibernate does not so the migration sql script might need to be altered to support any issues we find.

Maven build instructions

Since not all the modules are currently compiling (the only operations ones are dspace-api, dspace-services, dspace-xmlui) a special command is needed to build everything:

...

Before starting tomcat it is best to set a breakpoint in the org.dspace.core.HibernateFlywayIntegrator class on line 72 (this catches SQL exceptions caused by flyway & will be useful information if it fails).

How to migrate DSpace modules to the service api

Introduction

In the steps above we disabled the modules that are not compiling so step one is to enable the module you wish to migrate, by removing it from the exclusions from the profile. When enabled a lot of compiler errors will start to reveal themselves, the second step is to resolve all compile issues until the module compiles (more information & small tutorials are available below). Once everything compiles you can startup the application & begin testing. For non JSPUI modules you should be able to use the XMLUI module to create communities, collections, items, ... if you have started from a fresh database.

Tutorial java porting

For this tutorial I will explain how one would port the HandleServlet found in the JSPUI module. This is a fairly simple class with a couple of services.

 Step 1: Find & declare services

The first step when porting is to find all the services and declare them at the top. So scroll through the class & look for [serviceName]Impl.anyMethod missing methods on what are now database entities, below are two examples:

//Static call to a service method that will fail on compilation 
AuthorizeServiceImpl.authorizeAction(context, item, Constants.READ);
//Another static call to a service method
HandleServiceImpl.resolveToObject(context, handle);
//Method not found on item since item.canEdit() is a business method call & not a simple getter/setter
item.canEdit();
//Method not found on collection since collection.canEditBoolean(true) is a business method call & not a simple getter/setter
collection.canEditBoolean(true);

For each of the services you need use a factory call to retrieve them (or if you are working in a spring bean you can autowire them).

When we add the factory calls at the top of the class (at the top declaration isn't mandatory, but best that we stick to a single way of how to handle things, this makes it easier to see which services are already declared) we get the following:

protected AuthorizeService authorizeService = AuthorizeServiceFactory.getInstance().getAuthorizeService();
protected HandleService handleService = HandleServiceFactory.getInstance().getHandleService();
protected CommunityService communityService = ContentServiceFactory.getInstance().getCommunityService();
protected CollectionService collectionService = ContentServiceFactory.getInstance().getCollectionService();
protected ItemService itemService = ContentServiceFactory.getInstance().getItemService();
protected SubscribeService subscribeService = EPersonServiceFactory.getInstance().getSubscribeService();

The next step is to use the factories to resolve a lot of compilation issues, below are some examples:

//Before
AuthorizeServiceImpl.authorizeAction(context, item, Constants.READ);
///After 
authorizeService.authorizeAction(context, item, Constants.READ);
 
//Before
HandleServiceImpl.resolveToObject(context, handle);
//After
handleService.resolveToObject(context, handle);
 
//Before
item.canEdit();
//After (requires the item & a context, because the service is a singleton & doesn't hold a state the database object should always be passed)
itemService.canEdit(context, item);
 
//Before
collection.canEditBoolean(true);
//After (requires the collection & a context, because the service is a singleton & doesn't hold a state the database object should always be passed)
collectionService.canEditBoolean(context, collection, true);
 
//There could even be some other methods that now require an additional argument that didn't need it before:
//Before
xHTMLHeadCrosswalk.disseminateList(item);
//After (requires a context)
xHTMLHeadCrosswalk.disseminateList(context, item);
 

As seen in the example above some of the services require additional arguments, depending on the method this could be a context, database object, .... A complete list of methods that have changed in this manner is available here DSpace Service based api: API Changelist

Another change easily encountered is the fact that in older DSpace versions an array of objects was returned instead of a list. This has been changed to always return lists. So the following changes will also need to be made:

//Before
Community[] parents = c.getCommunities();
request.setAttribute("dspace.community", parents[0])
//After
List<Community> parents = c.getCommunities();
request.setAttribute("dspace.community", parents.get(0))
 
...