|
|
| (11 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | == Introduction to Templates Completion ==
| |
| | | | |
| − | The Code Recommenders Template Completion plug-in aims to provide automatically generated Eclipse templates, extracted from a database of mined API usage patterns and fitted to the context of the completion request.
| |
| − | This page contains in-detail information about the templates completion plug-in and how it can be used, maintained and extended by developers.
| |
| − |
| |
| − | For the rest of this introduction we will present a short scenario which helps the developer to understand the major tasks of the plug-in and possible obstacles in generating templates.
| |
| − | In the following we will present the general [[#Architecture]] of the plug-in by giving an overview of its components in [[#Components Overview]] and how they interact in [[#General Workflow]].
| |
| − | We will further explain the most [[#Important Concepts]] which further helps understanding the system and are vital to know for working on the plug-in.
| |
| − |
| |
| − | === Functionality ===
| |
| − |
| |
| − | Eclipse has a built-in templates engine which allows the user to define frequently used code snippets and to insert them with just a few clicks.
| |
| − | For a better adaption several variables can be included in order to make templates more dynamic and corresponding to the context in where they are inserted.
| |
| − | An overview is given by the [http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.jdt.doc.user/concepts/concept-template-variables.htm Eclipse help pages].
| |
| − | However, as the following example for creating an SWT button object illustrates, designing templates can be difficult and time-consuming.
| |
| − |
| |
| − | ; Default Eclipse SWT template for a new button:
| |
| − | <source lang="java">
| |
| − | ${buttonType:newType(org.eclipse.swt.widgets.Button)} ${button:newName(org.eclipse.swt.widgets.Button)}= new ${buttonType}(${parent:var(org.eclipse.swt.widgets.Composite)}, ${style:link(SWT.PUSH, SWT.TOGGLE, SWT.RADIO, SWT.CHECK, SWT.FLAT)});
| |
| − | ${button}.setLayoutData(new ${type:newType(org.eclipse.swt.layout.GridData)}(SWT.${horizontal:link(BEGINNING, CENTER, END, FILL)}, SWT.${vertical:link(CENTER, TOP, BOTTOM, FILL)}, ${hex:link(false, true)}, ${vex:link(false, true)}));
| |
| − | ${button}.setText(${word_selection}${});
| |
| − | ${imp:import(org.eclipse.swt.SWT)}${cursor}
| |
| − | </source>
| |
| − |
| |
| − | Therefore the Eclipse Recommenders Templates plug-in aims to automatically create such templates for (a) providing useful shortcuts to frequently written code and (b) to populate common practices which help new users to learn how frameworks are used.
| |
| − | However, much from the context of the completion request can influence the decision about how to (further) progress with an object, which is why presenting appropriate and well-adaptive templates is non-trivial.
| |
| − |
| |
| − | The following illustrates several obstacles in one example.
| |
| − | First, the declaration of b is not within the direct scope of the completion request, it's defined outside the method.
| |
| − | Second, there have already been methods called, so we shouldn't, for example, include a new constructor (it's not common for this scenario).
| |
| − | Third, "b" has not been qualified with a dot ("b.") when triggering the request, which usually is required to identify the variable.
| |
| − |
| |
| − | ; Example scenario for a templates completion request:
| |
| − | <source lang="java">
| |
| − | private Button b;
| |
| − |
| |
| − | private void doSomething(){
| |
| − | b = new Button(null, 0);
| |
| − | b.setText("...");
| |
| − | b<^Space>
| |
| − | }
| |
| − | </source>
| |
| − |
| |
| − | == Architecture ==
| |
| − |
| |
| − | [[Image:Recommenders templates arch.png|thumb|Dependencies between components]]
| |
| − |
| |
| − | This section contains a general overview about the whole plug-in architecture and how its components interact.
| |
| − | First, a diagram describing the structure and the dependencies between the components is displayed on the right-hand side.
| |
| − | Second, each component of the Plugin is given along with a short description of its role.
| |
| − | Finally, the default sequence of components interaction for generating templates is displayed.
| |
| − |
| |
| − | === Components Overview ===
| |
| − |
| |
| − | The following describes all classes introduced by this plug-in. Please note that it also depends on several components of the [[Recommenders]] framework, which won't be described, due to it's complexity.
| |
| − |
| |
| − | {| border="1" cellpadding="4" cellspacing="0"
| |
| − | |+ Table of Plugin components and short description of their roles.
| |
| − | ! style="background: #ffdead;" | Package / Class
| |
| − | ! style="background: #ffdead;" | Description
| |
| − | |-
| |
| − | ! style="background: #efefef;" | .templates
| |
| − | ! style="background: #efefef;" | Main components of the Plugins, control interaction.
| |
| − | |-
| |
| − | | CompletionProposalsBuilder
| |
| − | | Transforms PatternRecommendations into IJavaCompletionProposals which are applied on the editor content when the propoals is selected from the completion proposals menu.
| |
| − | |-
| |
| − | | CompletionTargetVariableBuilder
| |
| − | | Extracts the CompletionTargetVariable from an IIntelligentCompletionContext.
| |
| − | |-
| |
| − | | PatternRecommender
| |
| − | | Computes PatternRecommendations from the CallsModelStore.
| |
| − | |-
| |
| − | | TemplatesCompletionModule
| |
| − | | Prepares the Plugin by injecting dependencies.
| |
| − | |-
| |
| − | | TemplatesCompletionProposalComputer
| |
| − | | Controls the process of template recommendations.
| |
| − | |-
| |
| − | ! style="background: #efefef;" | .templates.code
| |
| − | ! style="background: #efefef;" | Components for transforming our information into Eclipse templates code.
| |
| − | |-
| |
| − | | CodeBuilder
| |
| − | | Builds Eclipse templates code from a list of method calls on a given variable name.
| |
| − | |-
| |
| − | | MethodCallFormatter
| |
| − | | Generates the String representation of a MethodCall.
| |
| − | |-
| |
| − | | MethodFormatter
| |
| − | | Generates the String representation of an IMethod.
| |
| − | |-
| |
| − | ! style="background: #efefef;" | .templates.types
| |
| − | ! style="background: #efefef;" | Encapsulates certain information. Only used by this Plugin.
| |
| − | |-
| |
| − | | CompletionTargetVariable
| |
| − | | Models the variable on which the completion was triggered.
| |
| − | |-
| |
| − | | JavaTemplateProposal
| |
| − | | Extends the TemplateProposal to customize the style of the template's entry in the completion popup.
| |
| − | |-
| |
| − | | MethodCall
| |
| − | | Models a call of a certain method on a given variable name.
| |
| − | |-
| |
| − | | PatternRecommendation
| |
| − | | Encapsulates one recommendation received from the models store.
| |
| − | |}
| |
| − |
| |
| − | === General Workflow ===
| |
| − |
| |
| − | The following sequence diagram illustrates the path from receiving a completion request to delivering appropriate template proposals.
| |
| − | The TemplatesCompletionProposalComputer controls the sequence by delegating tasks, so it first requests a [[#Completion Target Variable]] holding information about the context, as described later.
| |
| − | Second, it passes the target variable to the PatternRecommender, which is connected to the Code Recommenders' pattern store and selects the best patterns for the given variable.
| |
| − | Third, a collection of patterns (mainly a list of method calls) is given to CompletionProposalsBuilder which transforms the patterns into Eclipse template codes and combines all relevant information about the template in a JavaTemplateProposal (which can be processed by Eclipse).
| |
| − |
| |
| − | The task of transforming patterns (i.e. method call information) into template code is delegated to the [[#Code Builder]].
| |
| − | It combines the generation of the "environment" (e.g. <source lang="java">Text text = button.</source>) and the method call code (e.g. <source lang="java">getText();</source>).
| |
| − | More information about this process is given later.
| |
| − |
| |
| − | [[Image:Recommenders-templates-sequence1.png|Regular computation of templates]]
| |
| − |
| |
| − | == Important Concepts ==
| |
| − |
| |
| − | This section will consider how the most important components work in detail.
| |
| − |
| |
| − | === Target Variables ===
| |
| − |
| |
| − | This subsection will explain what information we need for template proposals in how it is encapsulated.
| |
| − |
| |
| − | === Pattern Recommender ===
| |
| − |
| |
| − | Here we will explain how the pattern recommender communicates which other plugins of the code recommenders system to obtain relevant patterns.
| |
| − |
| |
| − | === Code Builder ===
| |
| − |
| |
| − | This subsection will shortly illustrate how Eclipse templates work and how we generate them from our mined patterns.
| |
