The ArchiRequester Interface
This section covers the following topics
Overview
The ArchiRequester Interface is a VB6 com dll that can be used to facilitate communication between COM-aware applications and the AGMCGI. Essentially, it converts the XML returned from ARCHI into an easy to use object structure
that can be visually represented in another application.
This section provides a detailed explanation of the interface exposed by ArchiRequester as well as the object structure returned to calling applications.
Finally, we provide an example of using the ArchiRequester with Visio.
Detailed Interface specifications
The entire Archi Requester interface is exposed in one class, namely: clsArchiUpdateModelType.
It has the following public members:
Public Properties:
Name
|
Type
|
Description
|
NodeTypes
|
Collection (Node or NodeType)
|
Depending on whether a Meta or Instance model has been retrieved, this collection will contain NodeTypes or Nodes respectively
|
TimeOut
|
Long
|
Sets the length of time (in seconds) for Archi to wait before an HTTP request is times out.
|
Error
|
String
|
Should an error have occurred, ArchiRequester will put the error description in this property
|
ModelTypes
|
Collection (String)
|
A collection of modeltypes retrieved from Archi after it has successfully executed the RMT command
|
Models
|
Collection (String)
|
A collection of models retrieved from Archi after it has successfully executed the RMS command
|
Actions
|
Collection (String)
|
A collection of actions performed by Archi extracted from return XML after performing a command.
|
ReturnModelType
|
String
|
'META' or 'INSTANCE', set after retrieving a model from Archi
|
RequestName
|
String
|
A long name for the last request executed by Archi Requester
|
Userid
|
String
|
The UID of the last user to execute a request
|
Model
|
String
|
The last model name used in a request
|
ModelType
|
String
|
The last model type name used in a request
|
URL
|
String
|
The last URL used in a request
|
Proxy
|
String
|
Proxy setting of the Winsock object
|
RemoteHost
|
String
|
RemoteHost setting of the WinSock object
|
Result
|
String
|
The full result of the last HTTP response received
|
Public Methods:
Name
|
Type Returned (If function)
|
Description
|
UpdateStart
|
Boolean
|
Displays the info window and allows the user to change URL, Userid, Password, ModelType and ModelName. Returns TRUE if the OK button was pressed, otherwise it returns FALSE.
|
SetNumberOfItems(noOfItems As Integer)
|
N/A
|
Sets the size of the progress bar for the progress window
|
SetProgress(currentItem As Integer)
|
N/A
|
Sets the progress in the progressbar
|
AddProgressDescription(inString As String)
|
N/A
|
Allows the calling program to add text into the progress window.
|
UpdateEnd
|
N/A
|
Closes the progress window and unloads it from memory
|
SendUpdateRequest(ShapeX As String, ShapeY As String, ShapeHeight As String, ShapeWidth As String, ShapeVisioType As String, Node As String)
|
Boolean
|
Sends a UML2 request to Archi using the information passed to the function.
|
SendUpdateRelRequest(RelType As String, RelText As String, FromType As String, FromNode As String, FromConnPoint As Integer, ToType As String, ToNode As String, ToConnPoint
As Integer, RelName As String, InvRelName As String)
|
Boolean
|
Sends a UMR request to Archi using the information passed to the function
|
SendUpdateAttrRequest(Attrname As String, AttrVAlue As String, ShapeVisioType As String, Node As String)
|
Boolean
|
Sends a AUD request to Archi using the information passed to the function
|
SendUpdateRelAttrRequest(Attrname As String, AttrVAlue As String, RelType As String, FromType As String, FromNode As String, ToType As String, ToNode As String)
|
Boolean
|
Sends a UAR request to Archi using the information passed to the function
|
SendModelTypeListRequest()
|
Boolean
|
Sends a RMT request to Archi using the information passed to the function
|
SendModelListRequest(ModelType As String)
|
Boolean
|
Sends a RMS request to Archi using the information passed to the function
|
The ArchiRequestor Object Structure
When Archi Requester is used to retrieve a model from Archi, it translates the XML received from Archi into a COM object structure. This structure is accessable via the following property:
ArchiRequester.clsArchiUpdateModelType.nodetypes
This property returns a Collection Type, if a Meta Model has been retrieved, the collection will contain "NodeType"
instances, otherwise it will contain "Node" instances. The diagrams above show the object structures for both conditions.
Using the ArchiRequester Interface with Visio
When using Archi Requester with any COM-enabled application, some code must be written to convert the object
structures above into the Visual Model to be displayed and vice-versa. We have already written such a routine for Visio using VBA.
This section shows via code snippets and illustrations how Archi Requester should be invoked from within another application and the responses that can be expected from Archi Requester.
Appendix A contains detailed flowcharts illustrating the logic to be used in VBA applications to present Archi information
graphically. These flowcharts are useful for troubleshooting and debugging purposes and can also be used as guidelines for integrating Archi Requester with other VBA applications.
Starting a Request
In order to start an Archi Request, an application mustr first create the Archi Requester object. The following code shows how the object is created and how a request is started:
Dim oArchiUpdate As Object
Private Function StartArchiUpdateModelType() As Boolean
On Error GoTo errhandler
If oArchiUpdate Is Nothing Then
Set oArchiUpdate = Nothing
Set oArchiUpdate = CreateObject("ArchiRequester.clsArchiUpdateModelType")
End If
oArchiUpdate.TimeOut = 6000
StartArchiUpdateModelType = True
Exit Function
errhandler:
Set oArchiUpdate = Nothing
MsgBox "Error occurred initializing the Archi Requester DLL " & vbCrLf & "Error
number: " & Err.Number & vbCrLf & "Error description: " & Err.Description, vbOKOnly, "Archi Requester Error"
StartArchiUpdateModelType = False
End Function
Public Sub GetArchiModel()
On Error GoTo errhandler
If StartArchiUpdateModelType = True Then
If oArchiUpdate.UpdateStart = True Then
oArchiUpdate.TimeOut = 6000
Call oArchiUpdate.SendGetModelFromArchiRequest
If oArchiUpdate.ReturnModelType = "META" Then
Call DrawArchiMetaModel
Else
Call DrawArchiModel
End If
oArchiUpdate.UpdateEnd
Set oArchiUpdate = Nothing
End If
End If
End
errhandler:
MsgBox "Error occurred performing the Archi request " & vbCrLf & "Error number: " &
Err.Number & vbCrLf & "Error description: " & Err.Description, vbOKOnly, "Archi Requester Error"
End Sub
Once you have written this code in VBA, you may execute it by selecting Macros/ThisDocument/GetModel from the menu.
Once you have selected this option, Archi Requester will automatically pop up the information window (see illustration
below), this window will attempt to populate all settings with the last values entered by reading the Windows registry.
When you click on the "…" button next to the "Model Type" drowdown, Archi Requester will retrieve a list of all Models (Instance and Meta) from the URL specified and populate the DropDown.
By clicking on the "…" button next to the "Model Name" dropdown, you will cause Archi Requester to retrieve a list of all models for the selected model type and populate the "Model Name" dropdown.
The "Retrieve Only Own Relationships" checkbox can be checked if you want to retrieve ONLY relationships that have information for the current model already. This allows you to filter out existing relationships that may have been added in
Archi itself after the model was sent via ArchiRequester, or any pre-existing relationships that were not reflected in the model that was sent to Archi via ArchiReqiester.
To abort the operation, click on the "Cancel" button, or click on the "OK" button to retrieve the model selected.
Drawing the Model
Once you have clicked on the "OK" button on the Information Window, the window will disappear and the progress window will be displayed:
As soon as Archi Requester has completed retrieval and conversion of the model from Archi, it will yield control to the calling program and the "Close" button will appear on this window.
The calling program may now process the Archi Requester Object structure. It can post progress information back to
the progress window to inform the user of its own progress. The following is an example algorithm that does just this:
Private Sub DrawArchiModel()
Dim Node As Object
Dim LegalRel As Object
Dim Counter As Long
Dim SourceShape As Shape
Dim TargetShape As Shape
Dim Rel As Object
Dim MyShp As Shape
On Error GoTo errhandler
InfoCount = 0
Counter = 0
Debug.Print "Building Nodes"
oArchiUpdate.SetNumberOfItems (oArchiUpdate.nodetypes.Count)
oArchiUpdate.SetProgress (0)
For Each Node In oArchiUpdate.nodetypes
Debug.Print Node.Description
Counter = Counter + 1
oArchiUpdate.SetProgress (Counter)
oArchiUpdate.AddProgressDescription ("Drawing node: " & Node.Description)
Set MyShp = DrawNode(Node, Counter)
Next Node
Set Node = Nothing
Fully Contained Relationships
When sending a model from Visio to Archi, you may want to automatically create a relationship between items when the
one is fully contained within the other. The illustration on the right shows an example of this; When the Visio VBA code
sends this information to Archi via the Archi Requester, it will automatically detect that Actor1, Actor2 and Process1 are
fully contained within Boundary1. This relationship information will be sent to Archi using the reserved phrase "Fully
Contained" for the Visual Reltype name. Should you wish these relationships to be mapped in the Archi repository, simply add the following XML to your model type:
<RELMAPPING>
<ARCHIRELTYPE>contains</ARCHIRELTYPE>
<VISUALTYPE>Fully Contained</VISUALTYPE>
</RELMAPPING>
This will tell Archi to create a "contains" relationship in the repository every time it receives a request with a "Fully Contained" visual RelType.
Should you want Archi to ignore this mapping, just leave this XML out of the model type definition.
When a model is retrieved from Archi, the Visio VBA code will ignore any visual RelTypes with the name "Fully
Contained", since the relationship is implied automatically by the position of the items relative to each other.
Instance Class Attributes
When you have a class diagram with attributes as shown below, you may want to send it to Archi in such a way that the
classes are created as node instances in the repository, and the attributes on the classes are also created as different types of node instances with a relationship between the Class instance and the Attribute instance.
The Visio VBA code will automatically detect that you are sending a class diagram to an instance Model Type. Under
these circumstances, the VBA code will send a "create instance" request for every attribute in the class using the
reserved phrase "InstanceAttribute" as the visual NodeType name. Following this the VBA code will send through a
"create relationship" request with the Class name as the source and the attribute name as the target and the reserved phrase "has attribute" as the visual RelType name.
In order to take advantage of this feature, simply add the following XML mappings into your model type definition:
<NODEMAPPING>
<ARCHITYPE>Archi Instance Attribute</ARCHITYPE>
<VISUALTYPE>InstanceAttribute</VISUALTYPE>
</NODEMAPPING>
<RELMAPPING>
<ARCHIRELTYPE>contains</ARCHIRELTYPE>
<VISUALTYPE>has attribute</VISUALTYPE>
</RELMAPPING>
This XML will result in all attributes being represented in Archi by instances of the nodetype "Archi Instance Attribute", these instances will be related to the archi class instances via the "contains" RelType.
When retrieving a model from Archi, the Visio VBA code will automatically detect and handle the "InstanceAttribute" and "has attribute" structure and model it accordingly.
|
