In this Lesson

You will

  • Learn what code refactoring is (if the concept is new to you)
  • Learn how Soiree supports refactoring
  • Learn the right and wrong way to copy and paste Soiree items


Martin Fowler popularized the term refactoring in 1999 with his book “Refactoring: Improving the Design of Existing Code”. In that book he defined Refactoring in two ways:

As A Noun: a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior

As A Verb: to restructure software by applying a series of refactorings without changing its observable behavior

In this lesson we will focus on refactoring as a verb. We will briefly discuss refactoring and what it means in the context of a Soiree product and then perform some exercises that illustrate the points.

Refactoring is all about helping yesterday’s code fit into today’s requirements.
Given that product development is cloaked in a discovery process it is not hard to imagine the choices you make today may need to be adjusted in the future as the path of discovery adds to the pool of meaning. When that new understanding is obtained it is refactoring that allows you to harvest yesterday’s code without harming today’s requirements.

Why would you consider refactoring? Some words come to mind: clarity, simplicity, serviceability, refinement, and correction, to name a few. So, refactoring may be something simple such as renaming a file or it it may be something more profound such as restructuring an object hierarchy or adjusting the agent granularity in your scenes.

When should you consider refactoring? Refactoring is something you do all the time – a little at a time. Refactoring is not a project you undertake (although it can become a project if you put it off too long), rather, refactoring is how you work. You refactor because you want to do something else and refactoring helps you do that other thing. So, anytime you change the feature set of your product you should also consider fundamental adjustments to the underlying code – it may be time to refactor.

What we have here is a failure to refactor!
If you fail to explore the benefits of refactoring then over time you may find the software ‘house’ you have created is more like a collection of oddly shaped rooms nailed together rather than the magnificent edifice you had pictured in your mind.

There are 3 types of assets in a typical Soiree product that can be involved in your refactoring efforts:

  1. Soiree Items
    If an item file is renamed or moved to another package then the following information must be updated.
    • The package and item name stored in the item file must be changed to match to the new package and/or filename that contains the item.
    • A Soiree item can refer to other items by their id (package + name). So, any item that references a refactored item must be modified to use the new item id.
  2. Java classes built from Soiree items
    These are classes created by using the build button in a Soiree item editor. When a Soiree item is refactored then any Java classes that were built from the item must also be refactored because the package and name of the classes must always match the package and name of the item from which they were derived. Soiree editors build two types of java classes each with different refactoring needs
    • Purely Generated classes
      These are classes created entirely by Soiree. They are stored in the generated source folder (the src-gen folder in the Party project) and should never be modified manually because they are deleted and re-generated each time you use the build button in a Soiree editor. The Entity and CodeList items are examples of items that produce purely generated classes. These classes are not actually ‘refactored’ (changed) – they are simply deleted when the item is refactored and then rebuilt when you build the refactored item.
    • Handautic classes
      A handautic class is a generated class that can be tailored by hand-crafted code which is preserved in the event the class is regenerated. Agents and Datasources are two examples of items that create such a class. These items produce a superclass in the src-gen folder that is fully managed by automation and a subclass in the src folder that must be managed by hand. So, when these items are refactored Soiree will delete the classes in the src-gen folder (they are rebuilt the next time you press the build button). The developer is responsible for refactoring the subclass.
  3. Java files that you create without Soiree automation
    These are standard Java files you create and refactor using Eclipse.

This lesson’s exercises will demonstrate refactoring each of these assets.

Copy and Paste

You may copy and paste Soiree items inside of the Eclipse package explorer. Let’s say you want to make a copy of an item. You can copy the item to the clipboard and then paste it into some package in your project. When the item is pasted it will be refactored so that it’s internal package and item name match the file that was pasted.

If you copy and paste items using something other than Eclipse then the pasted item will not be refactored.

Refactor a Soiree Item that does not create Java classes

In this exercise you will refactor a Soiree item that does not have the ability to create Java classes.

  1. Right-click the PartyDefinition scene and select Refactor, Rename… from the context menu.

  2. Change the item name to PartyMaintenance.sxScene and press OK

  3. Check the item references for the renamed scene.

  4. Notice that the new scene is still referenced by the PartySplash scene.

  5. Open the PartySplash scene and check the properties of the party fish image button. Notice that the scene transition contains the refactored scene id.

  6. Leave the PartySplash scene open then set the keyboard focus back to the package explorer and undo the refactoring.

  7. When you undo the refactoring two things happen
    1. The scene name is changed back to PartyDefinition
    2. The PartySplash scene is closed and reopened because its contents were changed.
  8. If you check the party fish image button properties you will see the old scene id has been restored.

Refactor a Soiree Item with purely generated classes

In this exercise you will refactor a Soiree item that produces purely generated classes.

  1. Open the PartyTypes code list.

  2. This item has a build button which indicates it generates Java classes.

  3. The only classes created by the Code List Editor are purely generated classes that reside in the src-gen folder. Build the item if the class in the src-gen folder does not already exist.

  4. Move the PartyTypes code list to a new package by dragging it from the package to the package.

  5. When the item was refactored its class was removed from the src-gen folder.

  6. Right click the refactored item and select Code ListItem References… from the context menu.

  7. You will see the agent that uses this code list was refactored and is now referencing the code list item

  8. Drag the PartyTypes item back to the package.

Refactor a Soiree Item with handautic classes

In this exercise you will refactor a Soiree item that produces handautic classes.

  1. Agents produce classes in both the src and src-gen folders. Here are the classes for the PartyList agent.

  2. Refactor the agent by changing its name to PartyListRefactored
  3. When the rename is complete you will notice the classes in the src-gen folder have been removed but the classes in the src folder remain as they were.

    Hands Off
    Soiree never modifies classes in the src folder.
  4. The PartyList class now contains an error because the PartyListSuper class no longer exists.

  5. Open the refactored agent and build it. You now have a new set of classes for PartyListRefactored

  6. The automated portion of the handautic class has now been refactored.
  7. You must finish the refactoring of the handautic class by copying any customizations from the PartyList subclass into the PartyListRefactored subclass and then delete the PartyList subclass and package (the PartyList class contains no custom code so you can simply delete it).

  8. You should now refactor the agent back to its original name. Since there are no customizations in this agent you can simply delete the partlistrefactored package, rename the item, and rebuilt it.

Refactor Java files that you create

In this exercise you will refactor a standard Java file.

  1. Use Eclipse’s References tool to find all the places where the test.DatasourceTestInterface interface is used.

  2. The Search view will display the classes that reference the interface
    test.DatasourceTestInterface interface is used.

  3. Refactor the interface by changing its name to DatasourceTestInterface2

  4. Open up the PartyBrowse class and notice its reference to DatasourceTestInterface has been changed to DatasourceTestInterface2

  5. You will now change the interface name back to DatasourceTestInterface by requesting the change from inside one of the dependent classes.
    • In the PartyBrowse class left click on the DatasourceTestInterface2 name to select it

    • Request a refactoring operation to rename the item

    • The name will be displayed in a box and you will be asked to change the name and press ENTER

    • Change the name back to DatasourceTestInterface and press ENTER. The .java file will be renamed (along with all references to it)

Copy and Paste a Soiree Item

In this exercise you will copy and paste an item from within Eclipse

    1. Copy the PublicGroup item to the clipboard

    2. Paste the item into the package

    3. You will be asked to provide a new name because the item you are pasting has the same name as a file that already exists in the package.

    4. Change the item name to Administrator. Be sure to leave the .sxGroup file extension in the name.

    5. Open the Administrator group and notice the internal package and name agree with the filename and location.

    6. Delete the item.
    7. The Right Way
      The correct way to copy and paste Soiree items is from inside Eclipse.

    You will now copy and paste an item the wrong way.

    1. Copy the PublicGroup item to the clipboard

    2. Paste the item onto your desktop
    3. Copy the item from your desktop into the clipboard
    4. Paste the item into the package

    5. Open the item and notice the internal package name does not match the file’s location.

    6. Use Eclipse
      Always use Eclipse to copy and paste Soiree items.
    7. This situation can be resolved by using Eclipse to move the the item to another package.
      • Drag the bad PublicGroup item into the folder.
      • Open the item and notice the internal package name now matches the file location.

    8. You can now move the item back to the location where it belongs.
    9. Delete the item.

    You are done with this lesson.