Package Structure

[Thomas Mercer-Hursh]

In this project of mine where I am trying to model existing systems written in the Progress ABL, legacy code not being OO, I am a little unsure of the way I should be using packages.

For an example, let's take a program A, which runs A1 and A2 and includes I1 and I2.  A1 and A2 are run persistently and contain a number of internal procedure entry points that are run directly from A.   A also includes a number of internal procedures which are run from the main body of A.  A also runs a utility program U1.

We have decided to model each internal procedure as its own class in order to show the linkages, both between code segments and data elements.  Thus, A1 and A2 may contain no actual code if all of the code in them is contained within internal procedures.

It seems logical to me to create one level of package which corresponds to the compile unit.  Thus, one package would consist of all of the internal procedures of A1 along with A1 itself and another would consist of A2 and all of its internal procedures.  Correspondingly, one would expect to have a compile unit package for A which consisted of the main body, its internal procedures, and the two include files.  But, suppose that the include files are not exclusive to A, but rather are common include files used in many many programs.  In that case it seems appropriate to me to put I1 and I2 into another package, but to include them in the diagram for the A compile unit package and, of course, to include links from A to the includes.

What has me a little puzzled about this is that when I mock up something like this and export the package, the include files do show up in the XMI, but I don't see anywhere except the diagram where they are visible within EA, except as links in the A class.  Am I missing a way in which they would be visible?

Also, I am thinking of creating a second level of package which corresponds to a functional unit such as a menu item.  E.g., suppose these programs were all a part of customer maintenance, I might have a structure like:

AccountsReceivable
 CustomerMaintenance
   CM_Diagram
   A
     A_Diagram
     AIP1
     AIP2
     <seems like the includes should be visible here>
     <also U1>
   A1
     A1IP1
     A1IP2
   A2
     A2IP1
     A2IP2

So, in A_Diagram I want to show three packages, one containing A, AIP1, and AIP2; one containing U1, and one containing I1 and I2.  In CM_Diagram, I would like to show three (or five) packages, one each for A, A1, and A2 (possibly ones for the Is and Us).  I have mocked up the diagrams, but I'm not seeing properties corresponding to the associations other than the links.  Am I missing something?

I hope this is clear ... it seems harder to describe than the underlying reality, it just is a bit awkward mapping it onto the structures of UML because it isn't OO.

[«Midnight»]

Perhaps a composite structure diagram would be more appropriate for some of this.

As a thought experiment, consider the package structure in another light. Packages may be used to illustrate arbitrary groupings of things. As such, they are sometimes more useful in showing a conceptual breakdown of a system than for the structural decomposition of the actual code. [Of course, this is only one of many interpretations of packages, many of which can and do coexist. What I'm trying to get across is the idea, and the limitations thereof.]

You may be more successful if you think in terms of components, with callable interfaces - don't get too hung up on the OO aspects here, it works for legacy systems too.

David

[Thomas Mercer-Hursh]

For starters, I will admit that I am still a bit fuzzy on when to use Package and when to use component, as both seem to have the same properties.

The composite structure diagram is a possibility, but one of the things I am concerned about in diagrams is having them become so complex that one can no longer look at them easily.  Hence, thinking more in terms of different levels of diagram.  E.g., above the levels mentioned I was thinking in terms of a package per menu, each menu item being one element.  From the little experimenting I have done this means that one can drag one of the levels of package into the diagram of the next higher level and there is a nice compact list of the components.

I should also say that the first pass here is to create the XMI for the structure, but not the diagrams.  We're not sure that we are going to have the resources needed to generate the diagrams themselves computationally ... plus, the model will get very large.  There are about 3000 programs in the complete set.  And, the initial target here is analysis of what exists rather than design for what should exist.

One of the consequences of this focus is that mostly we only have what is empirical available to load.  In parallel to this effort, there will be other people collecting use cases and the like to try to create the conceptual background and eventually we will want to tie that to the implementation, but the initial load from the code and data will only have some limited empirical structural information available.  This includes the call structure, data references, and the menus.

[Paolo F Cantoni]

For starters, I will admit that I am still a bit fuzzy on when to use Package and when to use component, as both seem to have the same properties.

Join the club Thomas!  However, our reading of the [size=13]UML 2.1.1 Superstructure (formal)[/size] Specification is that packages are essentially namespaces and as consequence are containers.  Elsewhere we've (not the "Royal" we -  but a number of us) argued for grouping packages that don't generate namespaces (but below the namespace root).  At present we use a stereotyped "node" for this purpose - since you can't place a package under a non-package (in EA).

If we have a physical container of some kind (such as the output of a compilation unit), we use more "physical" elements than packages as the container.  There seems to be a conflation of concepts in the UML "Package".  This may be because of historical accident.

Paolo

[Thomas Mercer-Hursh]

Reading the specifications seems like the long road to enlightenment!

I have mixed feelings about the namespace aspects in this context.  In my own legacy code, there wouldn't be much of an issue since physical location, namespace, and menu structure are all pretty close, but with this customer I think things are a bit less orderly.

I suppose the question I would have, then, is what are the possible negative consequences of using a stereotype based on Package versus a stereotype based on a more generic type of node, especially given that this is not OO code.

I might note that the initial model here is necessarily a very concrete PSM, but there is interest in deriving a PIM or even CIM from it and then generating toward a new architecture using OO.  Any code generation from the PSM will be extremely simple and will not result in OO code.

[Paolo F Cantoni]

Reading the specifications seems like the long road to enlightenment!

Or madness!

However, as I see it you have two problems:
1) The conceptual problem of how UML allows you to group things together.
2) The practical problem of how EA allows you to group things together

As you suggest, diagrams are an implicit way of grouping things - Diagrams don't actually exist in the UML specification.

We found we had to play with a number of combinations then came to the conclusions we did.  For our purposes it's the lesser of a number of evils - but doesn't provide us with what we really need.  It really does depend upon your specific needs.

The problem is compounded somewhat because EA doesn't allow classifier features (such as operations and attributes) to be first-class citizens on diagrams.  In addition, you can't see the items in a diagram in the browser - only on the diagram itself.

HTH,
Paolo

[Thomas Mercer-Hursh]

The expectation at the customer is that direct operations on the data will do the heavy lifting in their analysis and the diagrams will be more of a communication tool.  The background issue here is that they have 3000 programs which cover POS, warehouse, manufacturing, distribution, etc. and they are beginning a move to SOA/ESB and would like to consider reinventing the pieces that live in the stores ... but they don't know what those pieces are!  So, in addition to loading the call structure and the data structure and the links between them, I would like to empirically discover and create various levels of grouping in order to help identify unique components by function and shared components.

[Thomas Mercer-Hursh]

If we have a physical container of some kind (such as the output of a compilation unit), we use more "physical" elements than packages as the container.

What type of physical container?

[Paolo F Cantoni]

What type of physical container?

Take your pick from anything in tObject - that is, an Element.  Diagrams exist in tDiagram and are not elements, packages exist in tPackage and have an equivalent tObject.  Anything in tPackage can only have a tPackage as a parent.  Anything in tObject (but not also in tPackage) can have another tObject as a parent (so long as it's not a (t)Package).

We typically use Components and Artifacts (depending on need) - but that's purely a convention (with some grounding in reality).  For pure grouping purposes we use node elements (merely because it "sounds" reasonable).  As I mentioned previously, they aren't "physical" but just group elements under them - so we stereotype them accordingly.

Does that help?
Paolo

[Thomas Mercer-Hursh]

Does that help?

I think so.  Thanks.

[Adam]

Because Nodes dont allow you to generate code for elements between them, I've developed a second workaround...

1. Choose a stereotype you will use to represent a non-namespace package, apply this to all the packages you dont want to be namespaces. I used 'container'.

2. Modify the code generation templates, where the packageNamespace is 'container' dont generate the namespace. This is pretty easy, you just add another condition to the existing exclusions (like the one that checks the global option of whether to generate namespaces).

Namespace Body:

%if packagePath == "" or genOptCPPGenNamespace != "T" or packageStereotype == "container"%
%endTemplate%

namespace %packageName%

You need to do a bit more messing around to remove the namespace in the implementation file - for c++ it inserts a

using namespace::classname

You can substring it, or like I did I totally removed the using declaration, and inserted a namespace instead

Import Section Impl:

$RSFileHeaders = %fileHeaders%
$eolPos = %FIND($RSFileHeaders, "\n")%
$RSFileHeaders = "\n" + %LEFT($RSFileHeaders, $eolPos)% + "\n\n"
$RSFileHeaders

Namespace Body Impl:

%if packagePath == "" or genOptCPPGenNamespace != "T" or packageStereotype == "container"%
%list="NamespaceImpl" @separator="\n\n\n" @indent=""%
%list="ClassImpl" @separator="\n\n\n" @indent=""%
%endTemplate%
namespace %packageName%
{

%list="NamespaceImpl" @separator="\n\n\n" @indent="    "%
%list="ClassImpl" @separator="\n\n\n" @indent="    "%

}

There you go, you have non-namespace packages. There is a caveat however, it only works for forward engineering, if you decide to sync code changes back the other way, then I'm pretty sure it will relocate the classes outside the 'container' package.

For this reason I think it still needs the new 'This package isnt a namespace' feature.

[Eve]

There you go, you have non-namespace packages. There is a caveat however, it only works for forward engineering, if you decide to sync code changes back the other way, then I'm pretty sure it will relocate the classes outside the 'container' package.

For this reason I think it still needs the new 'This package isnt a namespace' feature.

You're correct, it won't work for forward synchronization and the 'Package Per Namespace' option in the Directory import will move it.

[Paolo F Cantoni]

You're correct, it won't work for forward synchronization and the 'Package Per Namespace' option in the Directory import will move it.

Then... Could we have a proper fix please?

We already have higher level packages that AREN'T namespaces.  We just need lower level ones also!

Since EA now indicates the namespace root, it could be extended to indicate those packages that aren't namespaces also - whether by stereotype (or preferably by property).

The default value would be (*) Participates in Namespace (  ) Container/Grouping only

Paolo

[size=0]©2007 Paolo Cantoni, -Semantica-[/size]

[Eve]

We understand the usefulness of having such a feature, however I can't promise that it will be implemented or when.

[Paolo F Cantoni]

[size=13]Packages, Namespaces & groupings[/size] has additional, related information.

Paolo