edu.byu.ece.edif.core
Class EdifLibrary

java.lang.Object
  edu.byu.ece.edif.core.NamedPropertyObject
      edu.byu.ece.edif.core.EdifLibrary

All Implemented Interfaces:

EdifOut, Properties, Trimable, java.io.Serializable

public class EdifLibrary
extends NamedPropertyObject
implements EdifOut, Trimable

Represents a library which is an ordered list of EdifCell objects.

The EdifCell objects within the library are available for use within the structure of other EdifCell objects. Each EdifCell contained within the library must have a unique name.

The order of EdifCell objects within the library must conform to the EDIF "define before use" policy. This policy requires that all EdifCell objects instantiated within a higher EdifCell object as EdifCellInstance must be defined earlier in the library or earlier within a previously defined library. No EdifCell object can be instanced until it has been defined. Many of the methods associated with this object are used for managing the name space and ordering of EdifCell objects. One of the main purposes of this class is to make sure that this object ordering is preserved and maintained.

It is not necessary for all EdifCell objects to be used by the library are defined in the library. EDIF supports multiple libraries and it is possible that EdifCells used in a given library are actually defined in a "previous" library. The EdifLibraryManager class manages these dependencies between libraries. TODO: addCell changes - only have one addCell() method. This method will add the cell to the end of the library. Check to make sure that all of its internal cells (within current library) have been defined (make sure it is valid by construction) - remove addCell(cell, boolean) method. Naming issues: - throw NameDuplicationException - create a library without a manager? - Generate exceptions if there is a name clash when adding. - case matching for get cell - return copy of collection for get cells.

Version:

$Id:EdifLibrary.java 198 2008-04-16 21:14:21Z jamesfcarroll $

See Also:

EdifLibraryManager, EdifCell, Serialized Form

Field Summary

private EdifNameSpaceList<EdifCell>	_edifCells The list of cells defined within the library.
private EdifLibraryManager	_edifLibraryManager This is a reference to the parent EdifLibraryManager object.
private boolean	_external External Keyword

Constructor Summary

EdifLibrary(EdifLibraryManager elm, EdifNameable name)
Construct an empty EdifLibrary object with the specified EdifLibraryManager and EdifNameable object as its name.

EdifLibrary(EdifLibraryManager elm, EdifNameable name, boolean external)
Construct an empty EdifLibrary Object with the specified EdifLibraryManager, EdifNameable Object as its name, and value for external.

EdifLibrary(EdifLibraryManager elm, java.lang.String name)
Construct an empty EdifLibrary Object with the specified EdifLibraryManager and name.

EdifLibrary(EdifLibraryManager elm, java.lang.String name, boolean external)
Construct an empty EdifLibrary Object with the specified EdifLibraryManager, name, and value for external.

Method Summary

boolean	addCell(EdifCell cell) Add an EdifCell into the ArrayList at the earliest possible position in the library.
void	addCells(java.util.Collection<EdifCell> cells)
boolean	containsCell(EdifCell cell) Return true if the collection of cells contains the passed-in EdifCell.
boolean	containsCellByName(java.lang.String name) Return true if the collection of cells contains a cell by the passed-in name.
boolean	containsClashingCell(EdifCell cell) Indicate whether there is a Cell in the library that clashes with the passed-in cell.
boolean	deleteCell(EdifCell cell, boolean force) Delete a cell from the library and return whether or not the delete was successful.
protected boolean	deleteCellAux(EdifCell cell) Delete a cell from the library, and return whether or not the delete was successful.
java.util.Collection<EdifCell>	findBlackBoxes() Return all leafCell, non primitive EdifCell objects within the library.
java.util.Collection<EdifCellInstance>	findCellInstancesOf(EdifCell cell) This function returns all EdifCellInstances that reference the given in cell in this library.
java.util.Collection<EdifCellInstance>	findCellInstancesOf(EdifLibrary lib) This function returns all EdifCellInstances that reference cells from the passed-in library.
java.util.Collection<EdifCell>	findInstancedLibraryCells(EdifCell cell) This function returns a list of EdifCell objects instanced by the given EdifCell object that are contained in the current library.
java.util.Collection<EdifCell>	findInstancedLibraryCells(EdifLibrary lib) This function returns a list of EdifCell objects instanced by EdifCells of the passed-in EdifLibrary Object that are contained in the current library.
java.util.Collection<EdifCell>	findNonReferencedCells() This function will return a list of EdifCell objects that are not referenced anywhere within the current Library.
EdifCell	getCell(java.lang.String name) Return the EdifCell object in this library that is associated with the given String name.
java.util.Collection<EdifCell>	getCells() Return the EdifCell Objects in this library.
java.util.Collection<EdifCell>	getExternalReferencedCells()
java.util.Collection<EdifLibrary>	getExternalReferencedLibraries()
EdifLibraryManager	getLibraryManager() Return this library's library manager.
EdifNameable	getUniqueEdifCellNameable(EdifCell cell) Determine a unique name based on the given EdifCell's name that will not clash with any of the library's existing cells.
EdifNameable	getUniqueEdifCellNameable(EdifNameable en) Determine a unique name based on the given EdifNameable that will not clash with any of the library's existing cells.
java.util.List<EdifCell>	getValidCellOrder()
boolean	isExternal() Indicate whether this library was tagged with the
boolean	isPrimitiveLibrary() This method will examine each of the EdifCell objects in the library and determine if every EdifCell in the library is a primitive (see EdifCell.isPrimitive()).
java.util.Iterator<EdifCell>	iterator() Return a Collection of EdifCell objects contained by this library.
boolean	nameClash(EdifCell cell) Return whether or not the given EdifCell's name will clash with another cell's name in this library.
(package private) void	setLibraryManager(EdifLibraryManager libMan) Set this library's library manager to libMan.
void	toEdif(EdifPrintWriter epw) Convert this object to EDIF format and write it to the passed-in EdifPrintWriter Object.
java.lang.String	toString() Returns a String representation of this Object.
void	trimToSize() Trim this EdifLibrary Object and contained Trimmable Objects down to size.
private void	visitCell(EdifCell cell, java.util.List<EdifCell> finishedCells, java.util.List<EdifCell> unvisitedCells) Visit a cell during the topological sort for computing valid cell order.

Methods inherited from class edu.byu.ece.edif.core.NamedPropertyObject

addProperty, addProperty, addPropertyList, copyProperties, equals, equalsProperties, getEdifNameable, getName, getOldName, getProperty, getPropertyList, rename, rename, rename

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

_edifCells

private EdifNameSpaceList<EdifCell> _edifCells

The list of cells defined within the library.

_edifLibraryManager

private EdifLibraryManager _edifLibraryManager

This is a reference to the parent EdifLibraryManager object. This manager manages other related libraries in the library structure.

_external

private boolean _external

External Keyword

The external construct declares a library to which reference is made, but which is not actually present within the current EDIF file. This may include any library which has been exchanged by means outside the current EDIF file.

The structure and semantics of external are parallel to those of library except that external is known to be incomplete; external libraries that are declared should only contain minimal information. Any information present, such as status, must agree with the information available in the read's library of the same name. External represents one way in which reference can be made to external information from within an EDIF file.

External should occur within a file only with prior consent of the intended receiving party, since it must be assumed that the missing library has already been transmitted. This statement provides an explicit means of declaring libraries, providing a simple check for data completeness. It also provides a mechanism for renaming an external library, since the rename construct may be used here. Cells in external may not have contents sections. Any object referenced later should be defined here, including all names and interface declarations.

      edif ::=
      '(''edif' edifFileNameDef
      edifVersion
      edifLevel
      keywordMap
      { <status > | external | library | design |
      comment | userdata }
      ')'
      external ::=
      '(''external' libraryNameDef
      edifLevel
      technology
      {< status > | cell | comment | userData }
      ')'a
 

So, this means that external is parallel to library, all the cells in the external definition have only name and ports, the exact definition of these cells should be in other EDIF file, which has a library defined with the same name of this external name, or the accepting system has already had a library with the same name of this external name.

Constructor Detail

EdifLibrary

public EdifLibrary(EdifLibraryManager elm,
                   java.lang.String name)
            throws EdifNameConflictException,
                   InvalidEdifNameException

Construct an empty EdifLibrary Object with the specified EdifLibraryManager and name.

Parameters:

elm - The EdifLibraryManager to construct the library into

name - The name of the new EdifLibrary Object

Throws:

InvalidEdifNameException

EdifNameConflictException

EdifLibrary

public EdifLibrary(EdifLibraryManager elm,
                   EdifNameable name)
            throws EdifNameConflictException

Construct an empty EdifLibrary object with the specified EdifLibraryManager and EdifNameable object as its name.

Parameters:

elm - The EdifLibraryManager to construct the library into

name - The name of the new EdifLibrary object

Throws:

EdifNameConflictException

EdifLibrary

public EdifLibrary(EdifLibraryManager elm,
                   java.lang.String name,
                   boolean external)
            throws EdifNameConflictException,
                   InvalidEdifNameException

Construct an empty EdifLibrary Object with the specified EdifLibraryManager, name, and value for external.

Parameters:

name - The name of the new EdifLibrary Object

external - True if this is an external library

Throws:

InvalidEdifNameException

EdifNameConflictException

EdifLibrary

public EdifLibrary(EdifLibraryManager elm,
                   EdifNameable name,
                   boolean external)
            throws EdifNameConflictException

Construct an empty EdifLibrary Object with the specified EdifLibraryManager, EdifNameable Object as its name, and value for external.

Parameters:

name - The name-holding information Object of the new EdifLibrary Object

external - True if this is an External library

Throws:

EdifNameConflictException

Method Detail

addCell

public boolean addCell(EdifCell cell)
                throws EdifNameConflictException

Add an EdifCell into the ArrayList at the earliest possible position in the library. TODO: should this method even exist?

Parameters:

cell - The EdifCell to add to this EdifLibrary

Returns:

True if the cell was actually added to the library

Throws:

EdifNameConflictException

See Also:

deleteCell(EdifCell,boolean)

addCells

public void addCells(java.util.Collection<EdifCell> cells)
              throws EdifNameConflictException

Throws:

EdifNameConflictException

containsCell

public boolean containsCell(EdifCell cell)

Return true if the collection of cells contains the passed-in EdifCell.

Parameters:

cell - The cell to check whether or not it exists in this EdifLibrary

Returns:

True if the passed-in EdifCell Object is contained within this EdifLibrary

containsCellByName

public boolean containsCellByName(java.lang.String name)

Return true if the collection of cells contains a cell by the passed-in name.

Parameters:

name - The name of the cell to see if it exists by name within this EdifLibrary

Returns:

True if this EdifLibrary contains a cell by the name of the passed-in String

containsClashingCell

public boolean containsClashingCell(EdifCell cell)

Indicate whether there is a Cell in the library that clashes with the passed-in cell. A clash occurs when there is a cell in the library with the same name and the cell interfaces of the two cells is different.

Parameters:

cell - The cell to match up with among the cells in this library to see if a clashing cell exists

Returns:

True if this EdifLibrary contains an EdifCell that clashes with the passed-in EdifCell

deleteCell

public boolean deleteCell(EdifCell cell,
                          boolean force)

Delete a cell from the library and return whether or not the delete was successful.

Parameters:

cell - The cell to be deleted.

force - Forces the cell to be deleted even if it's still referenced within the library.

Returns:

True if the cell was deleted.

findBlackBoxes

public java.util.Collection<EdifCell> findBlackBoxes()

Return all leafCell, non primitive EdifCell objects within the library. These leafCells are called black boxes.

Returns:

A Collection of EdifCells contained within this library that are leaf cells and aren't primitives, or black boxes

See Also:

EdifLibraryManager.findBlackBoxes()

findCellInstancesOf

public java.util.Collection<EdifCellInstance> findCellInstancesOf(EdifCell cell)

This function returns all EdifCellInstances that reference the given in cell in this library. This will only search the current library. If no CellCellInstances are found, this method will return null. This method finds all instanced EdifCell objects (i.e. EdifCellInstances) in the current library.

Parameters:

cell - The cell to find cell instances of

Returns:

A Collection of EdifCellInstance Objects that refer to the passed in EdifCell

See Also:

EdifCell.findCellInstancesOf(edu.byu.ece.edif.core.EdifCell)

findCellInstancesOf

public java.util.Collection<EdifCellInstance> findCellInstancesOf(EdifLibrary lib)

This function returns all EdifCellInstances that reference cells from the passed-in library. This will only search the current library. If no CellInstances are found, this method will return null. This method finds all instanced EdifCell objects (i.e. EdifCellInstances) in the current library.

Parameters:

lib - The library that contains EdifCells that this method will find the EdifCellInstances of

Returns:

A Collection of EdifCellInstaces that refer to EdifCells in the passed-in library

See Also:

EdifCell.findCellInstancesOf(edu.byu.ece.edif.core.EdifCell)

findInstancedLibraryCells

public java.util.Collection<EdifCell> findInstancedLibraryCells(EdifCell cell)

This function returns a list of EdifCell objects instanced by the given EdifCell object that are contained in the current library. This is very similar to the EdifCell.getSubCellList() method with the exception that the returned subcells are limited to those that lie within this EdifLibrary.

Parameters:

cell - The cell that contains EdifCellInstances that refer to EdifCells this method returns a Collection of

Returns:

A Collection of EdifCells that are referenced by EdifCellInstances contained within the passed in EdifCell

findInstancedLibraryCells

public java.util.Collection<EdifCell> findInstancedLibraryCells(EdifLibrary lib)

This function returns a list of EdifCell objects instanced by EdifCells of the passed-in EdifLibrary Object that are contained in the current library. This is very similar to the EdifCell.getSubCellList() method with the exception that the returned subcells are limited to those that lie within this EdifLibrary.

Parameters:

lib - The library that contains EdifCells that contains EdifCellInstances that refer to EdifCells this method returns a Collection of

Returns:

A Collection of EdifCells that are referenced by EdifCellInstances contained within EdifCells contained within the passed in EdifLibrary

findNonReferencedCells

public java.util.Collection<EdifCell> findNonReferencedCells()

This function will return a list of EdifCell objects that are not referenced anywhere within the current Library. These EdifCell objects may be referenced from a different library.

Returns:

A Collection of EdifCells that exist in this library and that aren't referenced from within this library

See Also:

EdifLibraryManager.findNonReferencedCells(edu.byu.ece.edif.core.EdifCell)

getCell

public EdifCell getCell(java.lang.String name)

Return the EdifCell object in this library that is associated with the given String name. If no cell with the given name exists in the library, return null.

Parameters:

name - The name of the cell to fetch from this library

Returns:

An EdifCell object whose name equals the passed in String

getCells

public java.util.Collection<EdifCell> getCells()

Return the EdifCell Objects in this library.

Returns:

A Collection object of the EdifCell Objects in this EdifLibrary

getExternalReferencedCells

public java.util.Collection<EdifCell> getExternalReferencedCells()

Returns:

a Collection of EdifCell objects that are instanced in this library but defined in a different library.

getExternalReferencedLibraries

public java.util.Collection<EdifLibrary> getExternalReferencedLibraries()

Returns:

a Collection of EdifLibrary objects that contain cells that are instanced by this library.

getLibraryManager

public EdifLibraryManager getLibraryManager()

Return this library's library manager.

Returns:

The EdifLibraryManager Object of this EdifLibrary

getValidCellOrder

public java.util.List<EdifCell> getValidCellOrder()

Returns:

a List of EdifCell objects in valid order according to the define before use rule. The order is computed using a depth first search topological sort.

isExternal

public boolean isExternal()

Indicate whether this library was tagged with the

 external
 

tag.

Returns:

True if this is an external library

isPrimitiveLibrary

public boolean isPrimitiveLibrary()

This method will examine each of the EdifCell objects in the library and determine if every EdifCell in the library is a primitive (see EdifCell.isPrimitive()). If every EdifCell is a primitive, then this method will return true. Otherwise, it will return false.

Note that this method does not look for leaf cells. Instead, it searches for cells that are tagged as primitives. If all of the cells are leaf cells but not all of the cells have been tagged as primitive, this method will return false.

Returns:

true if this library contains only primitive cells

iterator

public java.util.Iterator<EdifCell> iterator()

Return a Collection of EdifCell objects contained by this library.

Returns:

An Iterator Object of the EdifCells in this library

nameClash

public boolean nameClash(EdifCell cell)

Return whether or not the given EdifCell's name will clash with another cell's name in this library.

Parameters:

cell - The EdifCell whose name will be checked against the names contained within the name space of EdifCell Objects

Returns:

true if the name of this EdifCell will clash with the name of a cell already existing within the library

getUniqueEdifCellNameable

public EdifNameable getUniqueEdifCellNameable(EdifNameable en)

Determine a unique name based on the given EdifNameable that will not clash with any of the library's existing cells. If there is no clash, the unique name will be the same as the original.

Parameters:

en - the name to use as a basis for a unique name

Returns:

an EdifNameable representing a unique name

getUniqueEdifCellNameable

public EdifNameable getUniqueEdifCellNameable(EdifCell cell)

Determine a unique name based on the given EdifCell's name that will not clash with any of the library's existing cells. If there is no clash, the unique name will be the same as the given cell's original name.

Parameters:

cell - this cell's name will be used as a basis for the unique name

Returns:

an EdifNameable representing a unique name

toEdif

public void toEdif(EdifPrintWriter epw)

Convert this object to EDIF format and write it to the passed-in EdifPrintWriter Object.

Specified by:

toEdif in interface EdifOut

Parameters:

epw - The EdifPrinterWriter Object that the EDIF data will be written to

toString

public java.lang.String toString()

Returns a String representation of this Object.

Overrides:

toString in class java.lang.Object

Returns:

A String representing this EdifLibrary Objects name, and contained EdifCell Objects

trimToSize

public void trimToSize()

Trim this EdifLibrary Object and contained Trimmable Objects down to size.

Specified by:

trimToSize in interface Trimable

deleteCellAux

protected boolean deleteCellAux(EdifCell cell)

Delete a cell from the library, and return whether or not the delete was successful.

Parameters:

cell - The cell to be deleted.

Returns:

true if the cell was deleted. false if the cell is not in the library or cell is null

See Also:

deleteCell(EdifCell,boolean)

setLibraryManager

void setLibraryManager(EdifLibraryManager libMan)

Set this library's library manager to libMan.

Parameters:

libMan - The library manager of this library

visitCell

private void visitCell(EdifCell cell,
                       java.util.List<EdifCell> finishedCells,
                       java.util.List<EdifCell> unvisitedCells)

Visit a cell during the topological sort for computing valid cell order.

Parameters:

cell - The EdifCell to visit

finishedCells - a List of finished cells

unvisitedCells - a List of unvisited cells