In addition of the correction of several bugs in the 3 libraries, some parts of the TAP library have changed. Consequently, if you developped your TAP service with the version 1.x, it should not be totally compatible any more with the new version. The following section will explain in more detail what you should modify in some files of your implementation to upgrade more easily your service. But basically here are the main modifications that you should know between v1.x and v2.0:

This section lists the main modifications to apply to your code in order to use v2.0 of the library instead of v1.x. Since this library lets customize several parts of a TAP service, some modifications you need to do may not be listed here. For those customized points, I advise you to look at the documentation, javadoc and/or GitHub commits. Here, only the most important modifications are listed ; they have been tested on the DemoASOV package delivered with the version 1.0 of the library.

1. In all classes

One of the big changes between the version 1.0 and 2.x, is the removal of all generic types (e.g. TAP<ResultSet>). This was indeed an awkward solution which had more constraints than flexibility. Without them, the syntax should be simpler.

public class DemoTAP_TAPFactory extends AbstractTAPFactory<ResultSet> {

	protected DemoTAP_TAPFactory(ServiceConnection<ResultSet> service) throws NullPointerException{
		super(service);
	}

	public ADQLTranslator createADQLTranslator() throws TAPException{
		return new PgSphereTranslator();
	}

	public DBConnection<ResultSet> createDBConnection(String jobId) throws TAPException{
		return new DemoTAP_DBConnection(jobId);
	}

}

public class DemoTAP_TAPFactory extends AbstractTAPFactory {

	protected DemoTAP_TAPFactory(ServiceConnection service) throws NullPointerException{
		super(service);
	}

	public ADQLTranslator createADQLTranslator() throws TAPException{
		return new PgSphereTranslator();
	}

	public DBConnection createDBConnection(String jobId) throws TAPException{
		return new DemoTAP_DBConnection(jobId);
	}

}

2. In your extension of DBConnection (if any)

The functions of the interface DBConnection have undergone a lot of modifications. The idea behind them is to move the database logic into DBConnection, so that the other classes of the library do not have to deal with transactions, database types, etc...

As you can see on the UML diagram. this last version of the library still provides the default implementation JDBCConnection. And of course, it has been modified so that being able to deal as nicely as possible with transactions and types. It is even able to detect whether transactions are supported by the database and whether the database has the notion of schemas (for instance, SQLite does not have this notion). Management of types and their conversion into TAP types is better managed than in v1.0 ; types of the main RDBMS should be totally detected and converted.

3. In TAPFactory

More explanations about the configuration of the factory can be found in this Getting Started.

public class DemoTAP_TAPFactory extends AbstractTAPFactory<ResultSet> {

    protected DemoTAP_TAPFactory(ServiceConnection<ResultSet> service) throws NullPointerException{
        super(service);
    }

    public ADQLTranslator createADQLTranslator() throws TAPException{
        return new PgSphereTranslator();
    }

    public DBConnection<ResultSet> createDBConnection() throws TAPException{
        return new DemoTAP_DBConnection();
    }

}

public class DemoTAP_TAPFactory extends AbstractTAPFactory {

	protected DemoTAP_TAPFactory(ServiceConnection service) throws NullPointerException{
		super(service);
	}

	public DBConnection getConnection(final String jobId) throws TAPException{
		return new JDBCConnection("org.postgresql.Driver", "jdbc:postgresql:" + DemoASOV.DB_NAME, DemoASOV.DB_OWNER, DemoASOV.DB_PWD, new PgSphereTranslator(), jobId, service.getLogger());
	}

	public void freeConnection(DBConnection conn){
		try{
			((JDBCConnection)conn).getInnerConnection().close();
		}catch(SQLException se){
			service.getLogger().error("Can not close the connection " + conn.getID(), se);
		}
	}

	public void destroy(){
		// nothing special to do here!
	}

}

4. Service description

outputFormats = OutputFormat<ResultSet>[2];
outputFormats[0] = new ResultSet2VotableFormatter(this);
outputFormats[1] = new ResultSet2SVFormatter(this, ",", true);

outputFormats = new OutputFormat[2];
outputFormats[0] = new VOTableFormat(this);
outputFormats[1] = new SVFormat(this, ",", true);

...
	private final OutputFormat[] formats;
	...
	public MyServiceConnection() throws UWSException{
		...
		formats = new OutputFormat[2];
		formats[0] = new DemoTAP_VOTableFormatter(this);
		formats[1] = new DemoTAP_CSVFormatter(",");
	}
	...
	public OutputFormat[] getOutputFormats(){
		return formats;
	}
...

...
	private final ArrayList<OutputFormat> formats;
	...
	public MyServiceConnection() throws UWSException{
		...
		formats = new ArrayList<OutputFormat>(2);
		formats.add(new VOTableFormat(this));
		formats.add(new SVFormat(this, ",", true));
	}
	...
	public Iterator<OutputFormat> getOutputFormats(){
		return formats.iterator();
	}
...

...
	public long[] getExecutionDuration(){
		return new long[]{3600,7200};
	}
...

...
	public int[] getExecutionDuration(){
		return new int[]{3600,7200};
	}
...

...
	private final UWSFileManager fileManager;

	public MyServiceConnection() throws UWSException{
		// Create a TAP files manager:
		fileManager = new LocalUWSFileManager(new File("MyTAPFiles"));
		...
	}
	
    public UWSFileManager getFileManager(){
        return fileManager;
    }
...

...
	private final TAPLog logger;

	public MyServiceConnection() throws UWSException{
		...
		logger = new TAPLog(fileManager);
	}
	...
	public TAPLog getLogger(){
		return logger;
	}
...

...
	public boolean isAvailable(){
		return true;
	}

	public String getAvailability(){
		return null;
	}
...

...
	private boolean available = false;
	private String availability = "TAP service not yet initialized!";
...
	public boolean isAvailable(){
		return available;
	}

	public String getAvailability(){
		return availability;
	}

	public void setAvailable(boolean isAvailable, String message){
		available = isAvailable;
		availability = message;
	}
...

...
	private final ArrayList<String> allowedGeometries;

	public MyServiceConnection() throws UWSException{
		...
		allowedGeometries = new ArrayList<String>(5);
		allowedGeometries.add("POINT");
		allowedGeometries.add("circle");
		allowedGeometries.add("Box");
		allowedGeometries.add("CONTAINS");
		allowedGeometries.add("intersects");
	}
	...
	public Collection<String> getGeometries(){
		return allowedGeometries;
	}
...

...
	private final ArrayList<FunctionDef> allowedUdfs;

	public MyServiceConnection() throws UWSException, TAPException{
		...
		allowedUdfs = new ArrayList<FunctionDef>(4);
		try{
			allowedUdfs.add(FunctionDef.parse("trim(txt String) -> String"));
			allowedUdfs.add(FunctionDef.parse("lower(txt varchar) -> VARCHAR"));
			allowedUdfs.add(FunctionDef.parse("upper(txt varchar) -> VARCHAR"));
			allowedUdfs.add(FunctionDef.parse("random() -> double"));
		}catch(ParseException pe){
			throw new TAPException("Can not initialize the TAP service! There is a wrong UDF definition: " + pe.getMessage(), pe);
		}
	}
	
	public Collection<FunctionDef> getUDFs(){
		return allowedUdfs;
	}
...

...
	public int[] getFetchSize(){
		return new int[]{-1, 10000}; // Synchronous: 10 000 rows per 10 000 rows ; Asynchronous: wait for the whole result
	}
...

5. User identification

...
	private final UserIdentifier identifier;

	public MyServiceConnection() throws UWSException, TAPException{
		...
		// Create a way to identify users (by IP address):
		identifier = new UserIdentifier(){
			public String extractUserId(UWSUrl urlInterpreter, HttpServletRequest request) throws UWSException{
				return request.getRemoteAddr();
			}
		};
	}
	
	public UserIdentifier getUserIdentifier(){
		return identifier;
	}
...

...
	private final UserIdentifier identifier;

	public MyServiceConnection() throws UWSException, TAPException{
		// Create a way to identify users (by IP address):
		identifier = new UserIdentifier(){
			public JobOwner extractUserId(UWSUrl urlInterpreter, HttpServletRequest request) throws UWSException{
				return new DefaultJobOwner(request.getRemoteAddr());
			}

			public JobOwner restoreUser(String id, String pseudo, Map<String,Object> otherData) throws UWSException{
				return new DefaultJobOwner(id, pseudo);
			}
		};
	}
	
	public UserIdentifier getUserIdentifier(){
		return identifier;
	}
...

6. Definition of table and column metadata

In v1.0, to declare tables and columns to publish, you had only the manual solution: create instances of TAPTable and TAPColumn.

Now, you can also import these metadata directly from the database schema TAP_SCHEMA thanks to the function DBConnection.getTAPSchema(). All standard tables and columns are then automatically converted into TAPTables and TAPColumns. This new solution is strongly recommended because it ensures the consistency between the database and the internal representation in the service ; in other words, between what is returned when the schema TAP_SCHEMA is interrogated with an ADQL query and the resource /tables.

public MyServiceConnection() throws TAPException, DBException, UWSException{
	...
	DBConnection dbConn = factory.getConnection("MetaConn");
	metadata = dbConn.getTAPSchema();
	getFactory().freeConnection(dbConn);
	...
}

Another quick solution is also proposed in this new version of the library: parse an XML document following the XML schema described by the IVOA in VODataService. Actually this document looks exactly like what will be returned by the resource /tables. Its root node is tableset and schema, tables, columns and foreign keys are listed and described there.

To convert a such document into a TAPMetadata object, you must use the parse named TableSetParser. Below is an example of it could be used:

...
	private final TAPMetadata meta;

	public MyServiceConnection() throws TAPException, DBException, UWSException{
    	...
		// Get the metadata from the given XML document:
		meta = (new TableSetParser()).parse(xmlFile);
    	
		// Update the TAP_SCHEMA schema in database:
		DBConnection dbConn = factory.getConnection("MetaConn");
	    metadata = dbConn.setTAPSchema(meta);
    	getFactory().freeConnection(dbConn);
	    ...
	}

	public TAPMetadata getTAPMetadata(){
		return meta;
	}
...

However, if you still want to use the manual solution, you have to modify your existing metadata creation in order to adapt it to v2.0. The following points have been modified:

• The table type is now an enum class - TableType - instead of a String value.
• Column types are better supported in v2.0. Thus, there is now one class to represent a column type, whereas before this information was composed of 2 separated values (a String and an integer): DBType.

Considering these two major modifications, the constructors and some functions of these two classes have slightly changed ; generally, the type and the position of a parameter in the parameters list have changed. Take a look to the following example to see such modifications applied to the functions addTable(String, TableType, String, String) and TAPTable.addColumn(String, DBType, String, String, String, String).

TAPTable t = tapSchema.addTable("schemas");
t.addColumn("schema_name", "schema name, possibly qualified", null, null, null, "VARCHAR", 32, true, true, true);
t.addColumn("description", "brief description of schema", null, null, null, "VARCHAR", 255, false, false, true);
t.addColumn("utype", "UTYPE if schema corresponds to a data model", null, null, null, "VARCHAR", 255, false, false, true);

TAPTable t = tapSchema.addTable("schemas");
t.addColumn("schema_name", new DBType(DBDatatype.VARCHAR, 32), "schema name, possibly qualified", null, null, null, true, true, true);
t.addColumn("description", new DBType(DBDatatype.VARCHAR, 255), "brief description of schema", null, null, null, false, false, true);
t.addColumn("utype", new DBType(DBDatatype.VARCHAR, 255), "UTYPE if schema corresponds to a data model", null, null, null, false, false, true);

...
	public MyServiceConnection() throws UWSException, TAPException{
		...
		// Update the database schema TAP_SCHEMA:
		try{
			DBConnection dbConn = tapFactory.getConnection("MetaConn");
			dbConn.setTAPSchema(metadata);
			tapFactory.freeConnection(dbConn);
		}catch(DBException de){
			throw new TAPException("Can not update the database with the given metadata!", de);
		}
		...
	}
...

7. Set the service as available

If you have set the "available" flag to false as suggested above, you have now to enable your TAP service at the end of the init(...) function of your servlet. You do that with the function setAvailable(booleam, String).

public class MyTAPServlet extends HttpServlet {
	private TAP tap = null;

	public void init(final ServletConfig config) throws ServletException{
		super.init();
		try{
			// 1. Create a TAP instance with the written ServiceConnection:
			tap = new TAP(new MyServiceConnection());

			// Set the service available:
			tap.getServiceConnection().setAvailable(true, "Demo's TAP service available!");
		}catch(Exception e){
			throw new ServletException(e);
		}
	}

	protected void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException{
		// 2. Forward all requests to the TAP instance:
		tap.executeRequest(request, response);
	}

At this stage, the old demo code (called DemoASOV), taken as example for all these migration instructions, does not have error any more and is fully functional. However, your implementation may still have some errors. In this case, you could merely follow the errors and try to fix them by yourself ; most of these errors should be simple to fix. If not, you can take a look to this Getting Started for comparison with what you have and you have implemented the factory and service description. Besides, the Javadoc of the library is complete and may be very helpful for you. And obviously, the documentation on this website may asnwer your questions.

If you still have problems that you figure out, you can send me an email. I will try to answer you as quick as possible.