com.scitools.understand

Class Entity

java.lang.Object

com.scitools.understand.Entity

public class Entity
extends java.lang.Object

Method Summary

Methods

Modifier and Type	Method and Description
void	draw(java.lang.String graph, java.lang.String filename, java.lang.String options) Generate a graphics file for the entity
boolean	equals(java.lang.Object obj)
java.lang.String	freetext(java.lang.String kind) Get the entity freetext of the given kind.
int	hashCode()
java.lang.String[]	ib(java.lang.String options) Return the Info Browser information for an entity.
int	id() Return a unique numeric identifier for the entity.
Kind	kind() Get a kind object representing the kind of the entity.
java.lang.String	language() Get the entity library text.
java.lang.String	library() Get the entity library text.
java.lang.String	longname(boolean preserveNamedRoots) If there is no long name defined, name() is returned.
java.lang.Number	metric(java.lang.String name) Return the value of a metric for an entity.
java.util.Map<java.lang.String,java.lang.Number>	metric(java.lang.String[] names) Return the values for an array of metric names as a map from name to value.
java.lang.String[]	metrics() Return a list of metric names available for the entity.
java.lang.String	name() Return the shortname for an entity.
java.lang.String	parameters() Get the entity library text.
Reference[]	refs(java.lang.String refkindstring, java.lang.String entkindstring, boolean unique) Return the references for this entity.
java.lang.String	simplename() Return the simple name of the entity.
java.lang.String	type() Get the entity type text.
java.lang.String	uniquename() Retrieve the unique name of an entity.
java.lang.String	value() Get the entity library text.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

id

public int id()

Return a unique numeric identifier for the entity. This identifier is not guaranteed to remain constant after the database has been updated.

Returns:

The unique name for the entity.

name

public java.lang.String name()

Return the shortname for an entity. For Java code, this may return a name with a single dot in it.

Returns:

uniquename

public java.lang.String uniquename()

Retrieve the unique name of an entity. An entity can be retrieved from a unique name using db.lookup_uniquename();

Returns:

The unique name for the entity.

simplename

public java.lang.String simplename()

Return the simple name of the entity.

Returns:

simple name

longname

public java.lang.String longname(boolean preserveNamedRoots)

If there is no long name defined, name() is returned. Examples of entities with long names include files, c++ members, and most ada entities.

For file entities, if preservedNameRoots is true, if a long filename includes a named root, it is preserved; otherwise, the named root is expanded to return the absolute filename.

Parameters:

preserveNamedRoots - true if named roots should be kept.

Returns:

the longname of an entity.

refs

public Reference[] refs(java.lang.String refkindstring,
               java.lang.String entkindstring,
               boolean unique)

Return the references for this entity. The parameters can be used to filter results. For more information on kind strings, see the Understand Perl API documentation.

Parameters:

refkindstring - A language-specific reference filter string. If null, references are not filtered.

entkindstring - A language-specific entity filter string the referenced entities. If null, references are not filtered.

unique - If true, return only the first matching reference to each unique entity.

Returns:

a list of references

kind

public Kind kind()

Get a kind object representing the kind of the entity.

Returns:

a Kind object

metrics

public java.lang.String[] metrics()

Return a list of metric names available for the entity.

Returns:

metric names

metric

public java.lang.Number metric(java.lang.String name)

Return the value of a metric for an entity.

Parameters:

name - The name of the metric. Must be a valid metric name, and not null.

Returns:

the value. Zero is returned if there is no value.

metric

public java.util.Map<java.lang.String,java.lang.Number> metric(java.lang.String[] names)

Return the values for an array of metric names as a map from name to value.

Parameters:

names - The names of metrics to retrieve values for

Returns:

A map from metric name to metric value.

draw

public void draw(java.lang.String graph,
        java.lang.String filename,
        java.lang.String options)
          throws UnderstandException

Generate a graphics file for the entity

Parameters:

graph - The name of the graph to generate. Available graphs vary by language and entity, but the name will be the same as the name in the Understand GUI. Some examples are:

• "Base Classes"
• "Butterfly"
• "Called By"
• "Control Flow"
• "Calls"
• "Declaration"
• "DependsOn"

filename - The name of the file. Only jpg, png, vdx, and svg file formats are supported on all platforms, so the filename parameter must end with either the extension .jpg, .png, .vdx or .svg.

options - Specifies the parameters used to generate the graphics. This may be null. The format of the options string is "name=value". Multiple options are separated with a semicolon. spaces are allowed and are significant between mutli-word field names, whereas, case is not significant. The valid names and values are the same as appear in that graphs right click menu and vary by view. They may be abbreviated to any unique prefix of their full names. Some examples are:

• "Layout=Crossing; name=Fullname;Level=AllLevels"
• "Display Preceding Comments=On;Display Entity Name=On"

Throws:

UnderstandException - If an error occurs. Some possible errors are:

• NoFont: no suitable font can be found
• NoImage: no image is defined or is empty
• NoVisioSupport: no Visio .vsd files can be generated on non-windows
• TooBig: jpg does not support a dimension greater than 64k
• UnableCreateFile: file cannot be opened/created
• UnsupportedFile: only .jpg, .png, or .svg files are supported

Additional error messages are also possible when generating a Visio file.

ib

public java.lang.String[] ib(java.lang.String options)

Return the Info Browser information for an entity.

Parameters:

options - This parameter may be null. If given, it specifies parameters used to create the text. The format of the options string is "name=value" or "{field-name}name=value". Multiple options are separated with a semicolon. Spaces are allowed and are significant between multi-word field names, whereas, case is not significant. An option that specifies a field name is specific to that named field of the Info Browser. The available field names are exactly as they appear in the Info Browser. When a field is nested within another field, the correct name is the two names combined. For example, in C++, the field Macros within the field Local would be specified as "Local Macros".

A field and its subfields may be disabled by specifying levels=0, or by specifying the field off, without specifying any option. For example, either of the will disable and hide the Metrics field:

• {Metrics}levels=0;
• {Metrics}=off;

The following option is currently available only without a field name.

Indent - this specifies the number of indent spaces to output for each level of a line of text. The default is 2.

The following options are currently available only with a field name. Not all options are available for all field names. The options that are available are the same as are displayed when right-clicking on the field name in the Understand tool. No defaults are given for these options, as the defaults are specific for each language and each field name.

• Defnfile
  • Short: displays the short filename where entities are defined
  • Long: displays the long filename where entities are defined
  • Relative: displays the relative filename where entities are defined
  • Off: never displays the filenames where entities are defined
• Dotrefs
  • On: displays references within longnames
  • Off: never displays references within longnames
• Filenames
  • Short: displays short filenames
  • Long: displays long filenames
  • Relative: display relative filenames
• Fullname
  • On: displays fullnames of entities when appropriate
  • Off: always displays short names of entities
• Inactives
  • On: displays inactive references
  • Off: never displays inactive references
• Levels
  • -1: show all nested fields
  • 0: hide the field name and all nested fields
  • n: show up to 'n' levels of nested fields; the default is 4
• Parameters
  • On: displays formal parameters of functions when appropriate
  • Off: never displays formal parameters
• References
  • On: displays file/line information and multiple references
  • Off: only displays the simple referenced entity once
• Returntypes
  • On: displays function return types when appropriate
  • Off: never displays function return types
• Sort
  • On: sorts information by name
  • Off: sorts information by reference file/line
  • Ref: sorts information by reference kind, then file/line
• Types
  • On: displays type text of entities when appropriate
  • Off: never displays type text

An example of a properly formatted option string would be:

"{Metrics}=off;{calls}levels=-1;{callbys}levels=-1;"

Returns:

The text of the info browser with respect to the passed in options.

type

public java.lang.String type()

Get the entity type text.

Returns:

type text

library

public java.lang.String library()

Get the entity library text.

Returns:

library text

value

public java.lang.String value()

Get the entity library text.

Returns:

library text

language

public java.lang.String language()

Get the entity library text.

Returns:

library text

parameters

public java.lang.String parameters()

Get the entity library text.

Returns:

library text

freetext

public java.lang.String freetext(java.lang.String kind)

Get the entity freetext of the given kind.

Parameters:

kind - name of the freetext kind

Returns:

freetext if it exists or an empty string