Bug 453909 - Inadequate BlackBox documentation
Summary: Inadequate BlackBox documentation
Status: NEW
Alias: None
Product: QVTo
Classification: Modeling
Component: Doc (show other bugs)
Version: unspecified   Edit
Hardware: PC Windows NT
: P3 normal (vote)
Target Milestone: ---   Edit
Assignee: Project Inbox CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on: 472482 326871
Blocks:
  Show dependency tree
 
Reported: 2014-12-02 11:21 EST by Ed Willink CLA
Modified: 2019-03-06 12:00 EST (History)
1 user (show)

See Also:

Attachments
Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Ed Willink CLA 2014-12-02 11:21:16 EST 
I'm trying to add a getURI() black box implementation to my MWE launched QVTO transformation and failing abysmally.

a) The QVTo Documentation section is incomplete. There is no working example of a *.qvto using a blackbox, since the BlackBox example has no *.qvto. Pasting the main() example into temp.qvto gives a syntax error. No missing module declaration. I can fix that but it doesn't help. What I want to know about is what library/import declaration to use.

b) I find no explanation for the "unit" level in the extension point. What do "name" and "namespace" signify? They seem irrelevant to me. Conversely they explain why nothing works.

The FAQ is similarly lacking and has non-hyperlink references.

c) I suspect that I need to know more to make a MWE launch work. What is it that I do now know? probably how to declare the extension point programmatically.
Comment 1 Sergey Boyko CLA 2014-12-02 11:36:07 EST 
Hi Ed,

I'm fully agree that documentation on BlackBox in QVTo is totally incomplete. Will be updated.

About launching QVTO from MWE. Am I correct that it is standalone execution of QVTO (i.e. by means of TransformationExecutor class) ?
Comment 2 Ed Willink CLA 2014-12-02 12:26:16 EST 
The extension point schema sheds some insight and also confusion. It would appear that the name and namespace should contribute to some kind of import declaration enabling the library name to be used. But how?

The extension point schema has a broken link to blackboxing.html

(In reply to Sergey Boyko from comment #1)
> About launching QVTO from MWE. Am I correct that it is standalone execution
> of QVTO (i.e. by means of TransformationExecutor class) ?

Yes.
Comment 3 Ed Willink CLA 2014-12-02 12:37:06 EST 
(In reply to Ed Willink from comment #2)
> The extension point schema sheds some insight and also confusion. It would
> appear that the name and namespace should contribute to some kind of import
> declaration enabling the library name to be used. But how?

Found a working example.

It looks as if in the documentation

main() {
	var date : ecore::EDate := createDate('2008-10-31');
	var isBefore := date.before(createDate('2008-11-01'));
	
	var eClass := object ecore::EClass {};
	var qname := eClass.getQualifiedName();
}

should be replaced by at least (and added to the FAQ)

import m2m.qvt.oml.ExampleJavaLib;

modeltype Ecore uses 'http://www.eclipse.org/emf/2002/Ecore';

transformation PruneUML(in ecore: Ecore, out Ecore);

main() {
	var date : ecore::EDate := createDate('2008-10-31');
	var isBefore := date.before(createDate('2008-11-01'));
	
	var eClass := object ecore::EClass {};
	var qname := eClass.getQualifiedName();
}

with a a little bit more so that it actually does something useful. Maybe insert an EAnnotation with today's date at the root and change all names to qualified names.

---

Further confusion arises from the failure of the editor to understand the plugin.xml extension point, making it appear as if a nested Eclipse session is needed to ensure that the blackbox is installed.

---

No idea what the purpose of the <library name in the extebnsion point is.

The extra <unit level is very flexible but an inordinate pain. Why not allow it to be omitted so that it is taken from the classpath of the class?

<extension point="org.eclipse.m2m.qvt.oml.javaBlackboxUnits">
   <library class="my.path.BlackBoxLibrary">
       <metamodel nsURI="http://www.eclipse.org/emf/2002/Ecore"/>
   </library>
</extension>

seems enough to configure 

import my.path.BlackBoxLibrary;

for the 99% of users who don't need to obfuscate their lookups.
Comment 4 Ed Willink CLA 2014-12-02 13:38:14 EST 
Found the great progress in Bug 326871 using @Module.

A real shame that it doesn't work. See Bug 326871.
Comment 6 Ed Willink CLA 2019-03-06 12:00:01 EST 
Bug 472482 identifies Bug 289982 as a source of design information that should be in /org.eclipse.m2m.qvt.oml.doc/references/blackboxing.html which should be revamped to be signifcantly more accurate and readable, have proper hyperlinks and an installable example.