com.togethersoft.openapi.rwi
Interface RwiPackage

public interface RwiPackage

extends RwiContainer

RwiPackage contains model's data (nodes, members, diagrams, and other packages)
in a directory-like structure.
Provides a set of methods for creating and deleting nodes, diagrams
and subpackages.

It is possible to get a package contents as an enumeration of nodes, diagrams or subpackages using
nodes, diagrams or subpackages methods respectively.

RwiPackages are physically represented either by directories or files.

Each RwiPackage represented by a directory contains:

• RwiNodes representing source code-based elements (classes,
  interfaces etc).
  
• other RwiPackages
  
• RwiDiagrams
  

To explain how Together uses these kinds of packages to keep model's data, let us suppose
in a new project a util package was created and in this package two classes and a note were created:

Suppose, that after that somebody created in the util package a new
Use Case diagram named "MyUseCase" with a note and an actor:

Now, the contents of the util directory on a disk will be the following:

util\

Class1.java

Class2.java

util.dfPackage

MyUseCase.dfUseCase

RwiPackage (name is "util") (represents util directory)\

RwiNode (name is "Class1") (represents Class1)

RwiNode (name is "Class2") (represents Class2)

RwiDiagram (name is "util") (represents the class diagram of util package - it is a physical package diagram (see below))

RwiDiagram (name is "MyUseCase") (represents the use case diagram MyUseCase)

RwiPackage (name is "util.dfPackage") (this package is physically stored in util.dfPackage file)\

RwiNode (name is "Note1" (represents Note1 in the class diagram)

RwiPackage (name is "MyUseCase.dfPackage") (this package is physically stored in MyUseCase.dfPackage file)\

RwiNode (name is "Actor1") (represents the actor in the use case diagram)

RwiNode (name is "Note1") (represents Note1 in the use case diagram)

An imported package is a package imported by the project.
The root packages for the imported packages are specified in the "Search/Classpath" tab in the project properties dialog (Advanced mode).

Each non-imported directory-RwiPackage
(it is a model's package,
the root packages of the model's packages are specified in the
"Project Paths" tab in the project properties dialog (Advanced mode))
has an automatically
created and associated with it class diagram called
a physical package diagram. This physical package diagram is always
synchronized with the package's contents (if something added a class to the package, the diagram will
reflect this change and show that class). In our example, the util's physical package diagram
is "util" RwiDiagram.

For non-imported directory-RwiPackage it is possible to get its physical package diagram
using getPhysicalDiagram method.

For all the diagrams method RwiContainer.getContainingPackage
will return a directory-RwiPackage (in our example, for both class diagram and use diagram
this method will return RwiPackage representing util directory).

If it is needed to get RwiPackage containing the design elements for the
the diagram then RwiDiagram.getDesignPackage method should be used.

RwiPackage can be examined on whether it is a directory-RwiPackage using
hasProperty(RwiProperty.DIRECTORY_PACKAGE).

Summary

Each RwiDiagram has one or two associated RwiPackages:

• Physical package diagram has two associated RwiPackages:
  
  
  
  1. directory-RwiPackage with the source code-based elements this diagram reflects.
     
  2. RwiPackage with the design elements for that diagram (notes etc). Such
     package is created only when you add the first design element to the diagram (for example, when you
     create the first note).
     
  
  
• Other diagrams have only one associated RwiPackage - the one that keeps the design
  elements.
  Note, that even if you create a new class diagram for the directory-RwiPackage
  it will not become a physical package diagram (physical package diagram is created automatically).
  Because of that if you create new classes in the package the newly created class diagram will
  not be aware of
  it. That is why it will have only one RwiPackage associated with it - the one that keeps
  design elements of that diagram.
  

Author:

TogetherSoft

Since: Together 3.0

See Also: nodes(), diagrams(), subpackages(), RwiProperty.DIRECTORY_PACKAGE

Methods inherited from interface com.togethersoft.openapi.rwi.RwiElement

accept, canCreateIncomingLink, canCreateOutgoingLink, canCreateOutgoingLink, canCreateOutgoingLinkByPattern, canCut, canDelete, codeElements, copy, createOutgoingLink, createOutgoingLinkByPattern, cut, delete, getCodeElement, getTimeStamp, getUniqueName, isDeleted, outgoingLinks

Methods inherited from interface com.togethersoft.openapi.rwi.RwiPropertyMap

addProperty, canAddProperty, canSetProperty, canSetProperty, getProperty, hasProperty, isPropertyReadable, isPropertyWritable, properties, properties, setProperty, setProperty

Method Detail

canCreateDiagram

public boolean canCreateDiagram(String shapeType)

Checks whether it is possible to create a new diagram with the specified value of
RwiProperty.SHAPE_TYPE property

Parameters:

shapeType the string value which needs to be assigned to the diagram's SHAPE_TYPE property. Cannot be
null.

Returns: true if it is possible to create a new diagram, false otherwise

See Also:

RwiProperty.SHAPE_TYPE

public boolean canCreateNode(String shapeType)

Checks whether it is possible to create a new node with the specified value of
RwiProperty.SHAPE_TYPE property.

Parameters:

shapeType the string value which needs to be assigned to the node's SHAPE_TYPE property. Cannot
be null.

Returns: true if it is possible to creates a new node, false otherwise

See Also:

RwiProperty.SHAPE_TYPE

public boolean canCreateNodeByPattern(String language, String patternName)

Checks whether it is possible to create a new node using the specified pattern.

Parameters:

language string with the name of the language for source code generation

patternName string with the name of the pattern being used.
Some pattern names are defined in the RwiPattern interface.

Returns: true if is possible to create a new node, false otherwise

See Also:

RwiLanguage, RwiPattern

public boolean canCreateSubpackage()

Checks whether it is possible to create a new subpackage of this package.

Returns: true if it is possible to create a new subpackage of this package,
false otherwise

public RwiDiagram createDiagram(String shapeType)

Creates a new diagram with the specified value of
RwiProperty.SHAPE_TYPE property

Parameters:

shapeType the string value which needs to be assigned to the diagram's SHAPE_TYPE property. Cannot be
null.

Returns: a new just created diagram.

For example, let us write a script which creates a new use case diagram with an actor named "CEO"
in the selected diagram's package:

public void run(IdeContext context){

RwiElement[] selectedRwiElements = context.getRwiElements();

RwiElement element  = selectedRwiElements[0];

if ( ! (element instanceof RwiDiagram) ) {

return;

}

RwiDiagram diagram = (RwiDiagram)element;

RwiDiagram newDiagram = diagram.getContainingPackage().createDiagram(RwiShapeType.USE_CASE_DIAGRAM);

RwiNodeReference actorReference = newDiagram.createNode(RwiShapeType.ACTOR);

RwiNode actor = actorReference.getNode();

actor.setProperty(RwiProperty.NAME, "CEO");

}

Note that if you select a package icon and run this script it will create a use case diagram
in that package, not in the package the
currently visible diagram belongs to (remember, package icons are RwiDiagrams - see RwiDiagram).

See Also:

RwiDiagram.createDiagram(java.lang.String), RwiProperty.SHAPE_TYPE, RwiShapeType.ACTOR, RwiDiagram

public RwiNode createNode(String shapeType)

Creates a new node in this package with the specified value of
RwiProperty.SHAPE_TYPE property. This method should not be used for generation
of the source code-represented elements like new classes or interfaces (for example,
someRwiPackage.createNode(RwiShapeType.CLASS) will not create a new class).
See createNodeByPattern method.

Or, you wish to create a node for a non-source code-represented element (a note, actor etc.),
it is be better to use
RwiDiagram.createNode method for the diagram
you want the node to be created in.

Parameters:

shapeType the string value which needs to be assigned to the node's SHAPE_TYPE property. Cannot
be null.

Returns: a new just created node

See Also:

RwiProperty.SHAPE_TYPE, createNodeByPattern(java.lang.String,java.lang.String), RwiDiagram.createNode(java.lang.String)

public RwiNode createNodeByPattern(String language, String patternName)

Creates a new node in this package using the specified pattern.

Parameters:

language string with the name of the language for source code generation

patternName string with the name of the pattern being used.
Some pattern names are defined in the RwiPattern interface.

Returns: a new just created node

For example, here is a script which creates a new class named "MyNewClass" and a new interface
named "MyNewInterface" in the selected diagram's containing package:

public void run(IdeContext context){

RwiElement[] selectedRwiElements = context.getRwiElements();

RwiElement element  = selectedRwiElements[0];

if ( ! (element instanceof RwiDiagram) ) {

return;

}

RwiDiagram diagram = (RwiDiagram)element;

RwiPackage rwiPackage = diagram.getContainingPackage();

RwiNode newClass = rwiPackage.createNodeByPattern(RwiLanguage.JAVA, RwiPattern.DEFAULT_CLASS); //creates a public class

newClass.setProperty(RwiProperty.NAME, "MyNewClass");

RwiNode newInterface = rwiPackage.createNodeByPattern(RwiLanguage.JAVA, RwiPattern.DEFAULT_INTERFACE); //creates a public interface

newInterface.setProperty(RwiProperty.NAME, "MyNewInterface");

}

Note that if you select a package icon and run this script it will create a class and interface
in that package, not in the package the
currently visible diagram belongs to (remember, package icons are RwiDiagrams - see RwiDiagram).

See Also:

RwiLanguage, RwiPattern

public RwiPackage createSubpackage()

Creates a new subpackage of this package. For example, let's write a script which
creates a new subpackage named "mySubpackage" in the package containing the selected diagram:

public void run(IdeContext context){

RwiElement[] selectedRwiElements = context.getRwiElements();

RwiElement element  = selectedRwiElements[0];

if ( ! (element instanceof RwiDiagram) ) {

return;

}

RwiDiagram diagram = (RwiDiagram)element;

RwiPackage subpackage = diagram.getContainingPackage().createSubpackage();

subpackage.setProperty(RwiProperty.NAME, "mySubpackage");

... //work with subpackage

}

Note that if you select a package icon and run this script it will create a subpackage
in that package, not in the package the
currently visible diagram belongs to (remember, package icons are RwiDiagrams - see RwiDiagram).

Returns: a new just created subpackage

public RwiDiagramEnumeration diagrams()

Returns an enumeration of diagrams within this package.

Returns: an enumeration of diagrams within this package

public RwiDiagram getPhysicalDiagram()

Returns the physical package diagram for this directory-RwiPackage. For other kinds
of packages returns null.

Returns: the physical package diagram for this directory-RwiPackage

See Also:

RwiProperty.DIRECTORY_PACKAGE

public RwiNodeEnumeration nodes()

Returns an enumeration of nodes within this package.

Returns: an enumeration of nodes within this package

public RwiPackageEnumeration subpackages()

Returns an enumeration of subpackages in this package. Note that
you can get containing package for this package using getContainingPackage() method.

Returns: an enumeration of subpackages in this package

See Also:

RwiContainer.getContainingPackage()