What's a Translation-Library?

Translation libraries are multiple translations that make up a library (or jar file to be exact). For example the query translation-library, currently consists of two translations: EJB-QL and Hibernate-QL.

Translation libraries are used to translate OCL expressions into other languages. For example, a translation-library could be used to translate an OCL body expression into a Hibernate-QL query, or EJB-QL query like you see below.

This OCL query
context org::andromda::contracts::Project::findByProjectTypeStatusAfterWentCurrentDate( type:String, status:String, wentCurrentDate:Date):Collection (Project) body : allInstances() -> select ( project | project.type = type and project.status = status and project.wentCurrentDate >= wentCurrentDate )
could be translated to: Hibernate-QL
from org.andromda.contracts.Project as project where project.type = :type and project.status = :status and project.wentCurrentDate >= :wentCurrentDate
or: EJB-QL
SELECT DISTINCT OBJECT(project) FROM Project project WHERE project.type = ?1 AND project.status = ?2 AND project.wentCurrentDate >= ?3

If you take a look at the Query Translation-Library, you'll see it does just what I describe above.

In addition to translating OCL query bodies, you could also translate things like constraints (i.e. OCL -> Java, OCL -> SQL, etc). OCL was orginally designed as a way of describing constraints in your model that weren't possible to express with UML drawings alone. OCL 2.0 has expanded on the constraint abilities (i.e.pre, post,inv) of OCL and have made OCL a fully fledged object expression language (which means it probably should be renamed to something like Object Expression Language).

How are Translation-Libraries Used?

Translation libraries are another type of plugin used and discovered by the AndroMDA framework. This means that just like Cartridges they will be found and made available to the framework by placing them on your project's classpath.

The major differences between a cartridge and translation-library is that translation-libraries are used with cartridges whereas cartridges can be used alone. For example: the EJB and Hibernate cartridges each have their own finder metafacade that extends the EntityQueryOperation to provide its own implementation of the getQuery method.

Previously each getQuery method would look up the tagged value that would store the query for either Hibernate-QL (for the Hibernate cartridge) or EJB-QL (for the EJB cartridge) and just return back the value from the stored tagged value. Using an OCL translation-library (the Query Translation-Library more specifically) you can define the query as OCL and store it as a contraint within your entity's finder method operation. Then using a translateConstraint method from the ModelElementFacade you can translate the OCL into Hibernate-QL or EJB-QL (or anything for that matter as long as the translation library supports it). Take a look at this code snippet that shows how you could look up and translate an OCL query into EJB-QL (assuming you had the query translation-library on your classpath) for an EJB metafacade getQuery method: 

                    
    public String handleGetQuery()
    {
        // this tells us to translate all "body" constraints using
        // the "EJB-QL" translation from the "query" library
        String[] translatedExpressions =
            this.translateConstraints(ExpressionKinds.BODY, "query.EJB-QL");
        String query = null;
        // we just get the first body constraint found (since there should
        // only be one)
        if (translatedExpressions != null && translatedExpressions.length > 0)
        {
            query = translatedExpressions[0];
        }
        return query;
    }