query/plugins/org.eclipse.viatra.query.patternlanguage.emf.ui/cheatsheets/gencode.xml

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet
      title="Generating Code from Queries">
   <intro href="https://wiki.eclipse.org/VIATRA/Query/UserDocumentation/API">
      <description>
          VIATRA Query provides a powerful Java API that you can use to integrate queries into Eclipse/OSGi/Java applications. VIATRA Query automatically generates Java source code for your query pattern definitions inside the <b>src-gen</b> folder located inside your VIATRA Query project. The code generation is carried out by a <b>builder</b> that can be disabled (i) either by disabling auto-build globally in your Eclipse workspace, (ii) or by a project-specific setting (project properties | VIATRA Query | Compiler | Uncheck &quot;Compiler is activated&quot;. As the compilation can be a resource-intensive task (especially for large .vql files), it is sometimes a good practice to disable it while you are actively working on your query definitions -- they can be completely tested and debugged without the compiler&apos;s support (see above, &quot;Executing queries on instance models with the Query Explorer&quot;)!<br/><br/>
          
          To use the generated VIATRA Query pattern matchers, either create your own plug-in project and add a dependency on the VIATRA Query plug-in (the EMF plug-ins corresponding to the referenced metamodels are automatically re-exported and made available to your code), or simply put your own code in the src/ folder of the query project.
          
          For a more detailed description of the generated code and the API, open the related help.
      </description>
   </intro>
   
   <item title="Inspecting the generated code">
      <description>
         For each query pattern definition, the generated code is placed inside the package of the query definition (.vql file), and it consists of the following main components:<br/>
* <b>XYZMatch</b>: a Data Transfer class corresponding to a match of the query pattern. A match is essentially a tuple that holds actual values of the header parameters. If VIATRA Query is able to correctly resolve the Java type of your model objects, the generated tuple class will be typesafe.<br/>
* <b>XYZMatcher</b>: the main entry point of the VIATRA Query API, used to initialize a pattern matcher (query evaluation) on an instance model and then perform subsequent queries.<br/>
* <b>XYZQuerySpecification</b>: (in the .util subpackage) helper class used to instantiate matchers.<br/>
* <b>XYZProcessor</b>: (in the .util subpackage) helper class that aids the programmer to formulate iteration cycles over sets of matches in a concise way. <br/>
      </description>
       <subitem label="To match a pattern on an EMF instance model (which will be the query scope), create a query engine object over it, then find the corresponding generated matcher class and use its .on method to instantiate it on the query engine. The matcher object will have useful methods such as getAllMatches(), some of them declared in the class itself, some of them in the interface VIATRA QueryMatcher. Refer to the Javadoc on method usage.">
      </subitem>
      <subitem label="During the lifetime of the query scope (ResourceSet, Resource or EObject containment hierarchy), the match sets will be incrementally maintained and therefore the pattern match retriever methods of the matcher object always return the up-to-date results virtually instantly. The actual (&quot;heavy&quot;) pattern matcher engine is constructed behind the scenes. The generated matcher class is only a lightweight wrapper; therefore you can instantiate it for the same query scope multiple times without significant performance penalties.">
      </subitem>
      <subitem label="Altogether, the public pattern query API can be used very simply to: (1) Initialize an incremental pattern matcher on any EMF Notifier (preferably Resource or ResourceSet, but can also be any EObject representing their respective containment subtrees). (2) Execute a query any time on the model, binding zero or more of the pattern parameters to input values, retrieving the result set immediately.">
      </subitem>
   </item>
   
   <item title="Check out advanced API features" href="https://wiki.eclipse.org/VIATRA/Query/UserDocumentation/API/Advanced">
       <description>
           Advanced API features (such as tracking changes in match sets, using the generic API to use VIATRA Query features without generating code etc) are discussed on the Eclipse wiki (open the related help).
       </description>
   </item>
   
</cheatsheet>