CDE Questions & Answers


This document contains a set of questions and answers related only to the Coordination Development Environment and not to coordination contracts in general. These document may be a good very quick reference guide on how to use CDE. If you have other questions, send us an e-mail at cde@atxsoftware.com and we will be very glad to answer.

 

Questions

  1. How can I create a new CDE Project?
  2. How can I add my Java components to the project? 
  3. What happens to the original components files after I have added them to the project?
  4. How can I create a new Contract?
  5. How can I add an existing contract to the project?
  6. What does it mean "compile" a contract? How can I do it?
  7. What does it mean "generate" a contract and/or a component?
  8. How can I compile a component?
  9. How can I generate contracts and components?
  10. What are the CDE generation options?
  11. Is there code, e.g contract operations, generated by default in order to allow the configuration of contracts or provide other functionalities?
  12. What are "coordinated" operations and what are "queries". What is their purpose? How can I specify operations to be "coordinated" or queries?
  13. Which are the files generated? How are they related to the contracts micro-architecture?
  14. Where are the generated files?
  15. Can I view/change the generated files?
  16. Can I compile the generated files in Java inside the CDE?
  17. I have a generation error message. What can I do then?
  18. I want to modify a contract. Do I have to recompile it?
  19. I want to modify a component. Can I do it? Are there any side-effects?
  20. I want to add a new contract but I have already generated everything. Do I need to regenerate all?
  21. Do I have to use CDE together with another Java Development Environment? If yes, which one(s)?
  22. How can I test contracts?
  23. The behaviour I observe when testing is not the one I expected when writing my contracts. Any ideas?
  24. I have Java compilation errors in the generated files. What might have gone wrong?
  25. Can I coordinate classes of objects for which I do not have the source code, for instance .class files or Java library classes?


Answers

  1. How can I create a new CDE Project?
    On the CDE menu click File, NewProject, choose a location and select a project name, normally with a .cdp extension. The project will be created at the location you specified, so you have to type the full path in case you want a project directory to be created as well.
  2. How can I add my Java components to the project?
    On the CDE menu click File, Add, Add Component or Project, select Add Component and select the .java file you wish to add. Normally, you would like to add such classes as contract participants.
  3. What happens to the original components files after I have added them to the project?
    The original .java files are copied to your project subdirectory called components. In the location from which you added each component, the .java file is renamed to .java.original. This is to avoid problems when loading your components from your Java project, thus having two components with the same name: the original ones and the ones that will be adapted/generated by the CDE. Now in your original, Java application you will have the .java.original file and the ones you will add after generation, so there should be no confilct problems. Your initial component files are copied now in the components subdirectory and the CDE works on top of these files. Therefore, it is easy to retrieve your original files which are still in their initial location, but renamed to .java.original.

  4. How can I create a new Contract?
    Click File, New, Contract and type the contract name with a .ctr extension. A contract template will appear in the editor and you may start editing your contracts.The contract template illustrates the full contract syntax, so you just need to delete the generic parts and write your own specific ones. Consult the
    CDE Contracts Specifications Reference for more details on how to write your contracts.

  5. How can I add an existing contract to the project?
    Click File, Add, Add Contract or Project, Add Contract and select the contract file you wish to add. After adding, the contract will be automatically compiled. In case of compilation errors, edit the contract by clicking File, Open File. Perform your changes, save and try to add the contract again. Notice that the contract files should normally have a .ctr extension to appear correctly on the editor.

  6. What does it mean "compile" a contract? How can I do it?
    Compiling a contract does not mean generating the byte code for it. The CDE contract compiler checks whether a specific contract specification is consistent with the CDE specification for contracts and, also, if its Java sections are correct in terms of Java syntax. It is very important to have in mind that contracts and Java execution semantics are not checked, so it is the programmers responsibility to write contracts with the correct execution semantics. To compile a contract, click Project, Compile, Contract Compiler or right-click on it in the editor and select Contract Compiler.

  7. What does it mean "generate" a contract and/or component?
    To "generate"a contract and/or component is to produce the Java code that implements the
    micro-architecture that we have developed for allowing coordination contracts to be superposed on components without the latter being aware of the contracts existence.
  8. How can I compile a component?
    In order to compile a component, click on its file on the project tree, right-click and select Java Compile.
  9. How can I generate contracts and components?
    Either select the component/contract (the name,not the file) on the project tree, right-click and select Generate in which case only the current component/contract will be generated, or, to generate everything either select Project, Generate from the CDE menu or right-click on the Project on the tree and select Generate .
  10. What are the generation options?
    The CDE offers two generation options:
    1. To generate with the animation facility. This option generates the code that supports testing using the CDE animator.
    2. To generate without the animation facility. This option is to be used when you know that you will not need the animation facility and prefer the generated code to be "cleaner". Our experience tells us that you will probably end up using both options: generate with animation, perform tests, and then generate again without animation to integrate the generated code in your Java application. To choose a generation option go to Project, Project Options and on the Project Settings dialog, click on the Generation tab and tick your generation option.
  11. Is there code, e.g contract operations, generated by default in order to allow the configuration of contracts or provide other functionalities?
    For each contract there are pieces of code generated by default in order to make its configuration feasible or provide other useful functionalities. These are the following:
    • Delete() operation: Removes a contract from its participants by removing the connectors from the chain of responsibility of each participant. However, because the host language is Java, it does not delete the contract object.
    • getParticipant() operations: A set of operations, one per participant, each of which returns a contract participant. For instance, for a participant Account savings an operation public Account getsavings(){ return savings; } will be generated.
    • setAttribute() and getAttribute() operations: For each contract attribute, two operations are generated: one to set the attribute value and one to return the attribute value. For instance, for a contract attribute double Limit, the operations generated will be: public void setLimit(double _Limit){Limit = _Limit;} and public double getLimit(){return Limit;}. These operations are to be used for the configuration of contracts.
    • initialize() operation: This is an operation called by default in each contract constructor. If you wish to perform some actions at contract initialization time, this is the operation to use. Notice that you have to define explicitly the operation in the contracts specification operation section.
    • String getName() and String toString() operations: These are operations that are used in the animator. The former returns the contract name and the latter the name of the contract together with the classes of its participants.

  12. What are "coordinated" operations and what are "queries". What is their purpose? How can I specify operations to be "coordinated" or "queries"?
    Operations of a participant (class) that are used as triggers in the coordination rules of a contract are called "coordinated" operations. For the current version of CDE, these can only be public operations.To specify an operation as "coordinated", right-click on the participant class, click on Coordinated Operations on the menu, and use the Selection Dialog to specify the operations. By default, initially, all public operations are specified as being coordinated. Alternatively, right-click on the operation on the project tree and check "Coordinated". Notice that participants constructors as well as the Java Object operation toString() can not currently be "coordinated". Operations selected as coordinated will be the ones that will appear in the generated file participantClassInterface.java and will be renamed according to the contracts design pattern.
    Query operations are the ones that do not change the state of an object, for instance operations that return a value. These operations are the ones that may participate in statements defined as conditions on state rules. By default, all operation names starting with "get" declare a query. To declare an operation as a query or not query, right click in the operation on the project tree and activate/deactivate "Query".
  13. Which are the files generated? How are they related to the contract micro-architecture?
    For each project, there are two sets of files generated that implement the contract design pattern: the components files and the contracts files: For each component, three files are generated:
    • componentClassName.java: For instance, for a component class Account, the generated file will be Account.java. This files contains the adapted version of the component, i.e the Subject and the SubjectToProxyAdapter parts of the pattern, merged into a singe Java class.
    • componentClassNameInterface.java: For instance, AccountInterface.java. It contains a Java interface with the component operations that are declared as "coordinated". It corresponds to the SubjectInterface part of the pattern.
    • IcomponentClassNamePartner.java: For instance, IAccountPartner.java. It corresponds to the ISubjectPartner part of the pattern and inherits from a CDE framework class CrdContractPartner that defines some common functionalites for managing the chain of responsibility, independently of specific partners.
    For each contract, the generated files are the following:
    • contractName.java: The implementation of the contract, corresponding to the Contract class of the pattern.
    • contractNameparticipantName_participantClassConnector.java: Corresponds to the Ct-i-SubjectConnector of the pattern. For each contract participant there is a corresponding file of this type. For instance, for a contract FlexiblePackage with participants checking and savings of class Account, the generated files will be FlexiblePackagechecking_AccountConnector.java and FlexiblePackagesavings_AccountConnector.java.

  14. Where are the generated files?
    The generated files are in the project subdirectory /generation/. Contracts are in generation/cde/contracts and participant files are in a subdirectory with the same name as their Java package. For instance, the generated files for a participant Account that belonged to the Java package banking, will be, after the generation, at the subdirectory /generation/banking.

  15. Can I view/change the generated files?
    Yes, the generated files appear in the project tree, just click the Generated Files folder. You can view them textually by right-clicking and select Edit Textual. You can also view these files by clicking File, Open File on the CDE menu. You may also modify them, but we strongly recommend not to do so in order to guarantee that the intended semantics is preserved.
  16. Can I compile the generated files in Java inside the CDE?
    Yes you can. Right-click on the file you wish to compile on the project tree and select Java Compile. Prior to doing so, however, do not forget to go to the Project, Project Options on the CDE menu and specify the CDE Runtime directory as well as the Java application source paths that may be required for Java compilation. Note that the Java compilation action builds the corresponding .class files under the directory .classes in your CDE project directory.
  17. I get a generation error message. What can I do?
    If there is a generation error message, its is probably because there is some information missing from the project. Try to add again your components/contracts. If this does not work, delete them from the project, add them again, and generate. If the problem persists, create a new project from scratch. If you still have a problem, please e-mail us at
    cde@atxsoftware.com.

  18. I want to modify a contract. Do I have to recompile it?
    Yes, you have to edit it, perform your modifications, save it, recompile and then generate it again.
  19. I want to modify a component. Can I do it? Are there any side-effects?
    The CDE operates on the component version that is in the project subdirectory /components. When performing modifications inside the CDE this is the component that gets changed. The original component is still in the location from which you loaded it to the project, but renamed to .java.original. Therefore, when modifying the component loaded to the CDE, you perform modifications on a copy of your original one. So there is no problem to modify, save, reload and generate again.
  20. I want to add a new contract but I have already generated everything. Do I need to regenerate all?
    If the contract has, as participants, classes that have already been added to the project, you just need to add the new contract and generate only that part. The participants files need to be generated only once and any number of contracts can be defined on top of them. Be careful, however, in cases in which you want to write a new contract with a rule on a participant's operation that you had specified as being not "coordinated" and have already generated the code for the participant. In such a case, you need to specify the opearation as being "coordinated" and regenerate the participant. On the other hand, if your new contract has a new participant you have to add the participant to the project and generate the adapted version of it.
  21. Do I have to use CDE together with another Java Development Environment? If so, which one(s)?
    CDE is a coordination contracts and not a Java development environment (JDE). Its current version is supporting contracts on top of Java components, (later versions will also support contracts on top of C++ components) and therefore, it must be used complementary to, but independently of, a Java development environment in which components under potential coordination and the rest of your application are being developed. The CDE is a stand-alone tool that is independent of any other Java Environment and therefore developing your Java application in a particular environment is not a pre-requisite for using the CDE.
  22. How can I test contracts?
    In order to test contracts, i.e. simulate their run time behaviour, you can use the CDE Animator. You can start the animator from the CDE menu by clicking Tools, Animator. Check the
    Testing Contracts section in the Quick Start Guide for more details.
  23. The behaviour I observe when testing is not the one I expected when writing my contracts, for instance, an infinite loop occurs. Any ideas?
    Any user of our coordination technology will quickly develop an eye for avoiding such pitfalls. For beginners, here are some tips:
    a. You have written a rule with a trigger operation but you have forgotten to specify the operation as "coordinated" on the participant.
    b. You forgot to specify an operation that does not change the state of an object as a "query" operation, thus triggering evaluation of state condition rules when you should not.
    c. You have built a genuine loop by calling back, in the reaction, an operation used in the trigger. Consult the contract micro-architecture for more details.

  24. I have Java compilation errors in the generated files. What may have gone wrong?
    If the generated files have Java compilation errors it is most likely that either you have a syntax/semantic error in the Java sections of a contract, or you have forgotten to add the CDE Runtime library to the required libraries of your Java project. To do so, go to Project, Project Options, and on the Project Settings dialog go to Files/Directories, CDE Runtime jar/directory. If you are compiling inside the CDE, perhaps you have forgotten to specify your application sources in the Source paths section of your Project Options. However, if everything else seems to be fine except for the generated code, then congratulations! You may have found a bug, so please e-mail us at
    cde@atxsoftware.com.
  25. Can I coordinate classes of objects for which I do not have the source code, for instance .class files or Java library classes?
    Unfortunately, the current version of the CDE does not support such features. You can only coordinate components for which the source code is available. Therefore, for instance, you may not define contracts that superpose behaviour on operations that belong to a Java class library. Soon, the CDE will support the coordination of components for which the source code is not available such as Java .class files.

 



© Copyright 2001 ATX Software SA. All rights reserved.