byucc.edif
Class EdifLibrary

java.lang.Object
  byucc.edif.NamedPropertyObject
      byucc.edif.EdifLibrary

All Implemented Interfaces:

EdifOut, Nameable, Properties, Trimable, java.io.Serializable

public class EdifLibrary
extends NamedPropertyObject
implements EdifOut, Trimable, java.io.Serializable

Represents a library which is an ordered list of EdifCell objects. The order of EdifCell objects within the library must conform to the EDIF "define before use" policy. In other words, all EdifCellInstance objects contained by a given EdifCell object must be defined in the library before the given EdifCell object has been. 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 cells 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.

To Do:

Version:

$Id: EdifLibrary.java,v 1.96 2005/08/05 18:33:05 nhr2 Exp $

Author:

Welson Sun, Mike Wirthlin, Tyler Anderson

See Also:

EdifLibraryManager, EdifCell, Serialized Form

Field Summary

private ArrayListNameSpaceResolver	_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 The external construct declares a library to which reference is made, but which is not actually present within the current EDIF file.

Constructor Summary

EdifLibrary(EdifNameable name)
Constructs an empty EdifLibrary Object with the specified EdifNameable Object as its name.

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

EdifLibrary(java.lang.String name)
Constructs an empty EdifLibrary Object with the specified name.

EdifLibrary(java.lang.String name, boolean external)
Constructs an empty EdifLibrary Object with the specified 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.
boolean	addCell(EdifCell cell, boolean earliest) Add an EdifCell into the ArrayList at the earliest or latest position, based on the earliest parameter.
boolean	containsCell(EdifCell cell) Returns true if the collection of cells contains the passed-in EdifCell.
boolean	containsCellByName(java.lang.String name) Returns true if the collection of cells contains a cell by the passed-in name.
boolean	containsClashingCell(EdifCell cell) Indicates whether there is a Cell in the library that clashes with the passed-in cell.
boolean	deleteCell(EdifCell cell, boolean force) Deletes a cell from the library, and returns whether or not the delete was successful.
protected boolean	deleteCellAux(EdifCell cell) Deletes a cell from the library, and returns whether or not the delete was successful.
java.util.Collection	findBlackBoxes() Returns all leafCell, non primitive EdifCell objects within the library.
java.util.Collection	findCellInstancesOf(EdifCell cell) This function returns all EdifCellInstances that reference the given in cell in this library.
java.util.Collection	findCellInstancesOf(EdifLibrary lib) This function returns all EdifCellInstances that reference cells from the passed-in library.
int	findEarliestPositionToAdd(EdifCell cell) This method will find the earliest position in the library in which the given EdifCell can be added.
java.util.Collection	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	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.
int	findLatestPositionToAdd(EdifCell cell) This method will find the latest position in the library in which the given EdifCell can be added.
java.util.Collection	findNonReferencedCells() This function will return a list of EdifCell objects that are not referenced anywhere within the current Library.
java.util.Collection	findPortRefsOf(EdifCell cell) This function will return a list of EdifPortRefs in the entire library that reference the ports of the passed in cell.
EdifCell	getCell(java.lang.String name) Return the EdifCell object in this library that is associated with the given String name.
java.util.Collection	getCells() Returns the EdifCell Objects in this library.
EdifLibraryManager	getLibraryManager() Returns this library's library manager.
NameSpaceResolver	getNameSpaceResolver()
java.util.Collection	getNextCells(EdifCell cell) Return the collection of cells that are defined after the specified cell in the libarary.
java.util.Collection	getPreviousCells(EdifCell cell) Return the collection of cells that are defined before the specified cell in the libarary.
boolean	isExternal() Indicates whether this library was tagged with the external tag.
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.isLeafCell()).
boolean	isValid() Verify that the Manager is valid (The ordering of the cells are OK).
java.util.Iterator	iterator() Return a Collection of EdifCell objects contained by this library.
boolean	nameClash(EdifCell cell) Returns whether or not the given string name will clash with another EdifCell's name.
void	setLibraryManager(EdifLibraryManager libMan) Sets this library's library manager to libMan.
void	tagLeafCellsAsPrimitives() Tags all leaf cells as primitive.
void	tagPrimitives(EdifLibrary primitives) Tags primitives in this library based on whether or not they match cells in the passed in library.
void	toEdif(EdifPrintWriter epw) Converts this object to EDIF format and writes it to the passed-in EdifPrintWriter Object.
java.lang.String	toString() Returns a String representation of this Object.
void	trimToSize() Trims this EdifLibrary Object and and contained Trimmable Objects down to size.
void	validateOrder() Re-orders the cells into a proper order (if they aren't already).

Methods inherited from class byucc.edif.NamedPropertyObject

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

Methods inherited from class java.lang.Object

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

Field Detail

_edifCells

private ArrayListNameSpaceResolver _edifCells

The list of cells defined within the library. The key of this map is the name of the EdifCell (as obtained from the getName() method) and the value is the actual EdifCell object.

_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 transimitted. 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
     {  | 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.

_edifLibraryManager

private EdifLibraryManager _edifLibraryManager

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

Constructor Detail

EdifLibrary

public EdifLibrary(java.lang.String name)

Constructs an empty EdifLibrary Object with the specified name.

Parameters:

name - The name of the new EdifLibrary Object

EdifLibrary

public EdifLibrary(EdifNameable name)

Constructs an empty EdifLibrary Object with the specified EdifNameable Object as its name.

Parameters:

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

EdifLibrary

public EdifLibrary(java.lang.String name,
                   boolean external)

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

Parameters:

name - The name of the new EdifLibrary Object

external - True if this is an External library

EdifLibrary

public EdifLibrary(EdifNameable name,
                   boolean external)

Constructs an empty EdifLibrary Object with the specified 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

Method Detail

addCell

public boolean addCell(EdifCell cell)

Add an EdifCell into the ArrayList at the earliest possible position in the library.

Parameters:

cell - The EdifCell to add to this EdifLibrary

Returns:

True if the cell was actually added to the library

See Also:

addCell(EdifCell,boolean)

addCell

public boolean addCell(EdifCell cell,
                       boolean earliest)

Add an EdifCell into the ArrayList at the earliest or latest position, based on the earliest parameter. This method makes sure that a cell with a duplicate name is not added to the library.

Parameters:

cell - The EdifCell to add to this EdifLibrary

earliest - If true then place the given cell at the earliest location in the library. If false, place at the latest location in the library

Returns:

True if the cell was actually added to the library

containsCell

public boolean containsCell(EdifCell cell)

Returns 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)

Returns 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)

Indicates 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)

Deletes a cell from the library, and returns 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.

deleteCellAux

protected boolean deleteCellAux(EdifCell cell)

Deletes a cell from the library, and returns 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)

findEarliestPositionToAdd

public int findEarliestPositionToAdd(EdifCell cell)

This method will find the earliest position in the library in which the given EdifCell can be added. This method check all cells in the library and find those in the library that are referenced by given EdifCell object. This method will return a library postion that insures that the EdifCellInstance objects referenced in this given EdifCell are already defined.

Note that this method will ignore EdifCellInstances of the given EdifCell that are not defined in this library.

Parameters:

cell - The cell to add.

Returns:

The earliest integer postion in which this cell can be added into the ArrayList of Cells.

See Also:

EdifLibraryManager.findEarliestLibraryToAdd(byucc.edif.EdifCell, boolean)

findLatestPositionToAdd

public int findLatestPositionToAdd(EdifCell cell)

This method will find the latest position in the library in which the given EdifCell can be added. This method check all cells in the library and find those EdifCells in the library that instance this given EdifCell object. This method will return a library postion that insures that the given EdifCell object is defined before other library elements use it.

Parameters:

cell - The cell to add.

Returns:

The latest integer postion in which this cell can be added into the ArrayList of Cells.

See Also:

EdifLibraryManager.findLatestLibraryToAdd(byucc.edif.EdifCell, boolean)

findPortRefsOf

public java.util.Collection findPortRefsOf(EdifCell cell)

This function will return a list of EdifPortRefs in the entire library that reference the ports of the passed in cell. This method will return null if no EdifPortRefs are found.

Parameters:

cell - The cell who has the ports to check the port references for.

Returns:

A Collection Object that contains ports refs referring to ports of the passed-in EdifCell

See Also:

EdifLibraryManager#findPortRefsOf

findCellInstancesOf

public java.util.Collection 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(byucc.edif.EdifCell)

findCellInstancesOf

public java.util.Collection 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(byucc.edif.EdifCell)

findInstancedLibraryCells

public java.util.Collection 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 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 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()

findBlackBoxes

public java.util.Collection findBlackBoxes()

Returns 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()

getLibraryManager

public EdifLibraryManager getLibraryManager()

Returns this library's library manager.

Returns:

The EdifLibraryManager Object of this EdifLibrary

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 getCells()

Returns the EdifCell Objects in this library.

Returns:

A Collection object of the EdifCell Objects in this EdifLibrary

getNameSpaceResolver

public NameSpaceResolver getNameSpaceResolver()

getNextCells

public java.util.Collection getNextCells(EdifCell cell)

Return the collection of cells that are defined after the specified cell in the libarary.

Parameters:

cell - The cell that designates the point after which cells will begin to be returned

Returns:

A Collection of EdifCell objects defined after the passed-in EdifCell Object

getPreviousCells

public java.util.Collection getPreviousCells(EdifCell cell)

Return the collection of cells that are defined before the specified cell in the libarary.

Parameters:

cell - The cell that designates the point where the list of cells stops

Returns:

A Collection of EdifCell objects defined before the passed-in EdifCell Object

isExternal

public boolean isExternal()

Indicates 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.isLeafCell()). If every EdifCell is a primitive, then this method will return true. Otherwise, it will return false.

In most cases, library primitives are grouped together in a single library. It may be necessary to find a library of primitives when trying to determine the proper library to add a primitive into the design.

Returns:

True if this library contains only primitive cells

iterator

public java.util.Iterator iterator()

Return a Collection of EdifCell objects contained by this library.

Returns:

An Iterator Object of the EdifCells in this library

isValid

public boolean isValid()

Verify that the Manager is valid (The ordering of the cells are OK).

Returns:

True if this is a valid library

nameClash

public boolean nameClash(EdifCell cell)

Returns whether or not the given string name will clash with another EdifCell's name.

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 already exists in the current list of EdifCells

setLibraryManager

public void setLibraryManager(EdifLibraryManager libMan)

Sets this library's library manager to libMan.

Parameters:

libMan - The library manager of this library

tagLeafCellsAsPrimitives

public void tagLeafCellsAsPrimitives()

Tags all leaf cells as primitive.

tagPrimitives

public void tagPrimitives(EdifLibrary primitives)

Tags primitives in this library based on whether or not they match cells in the passed in library.

Parameters:

primitives - The library that contains primitives that will be compared against all cells in this library to match with primitives

toEdif

public void toEdif(EdifPrintWriter epw)

Converts this object to EDIF format and writes 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()

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

Specified by:

trimToSize in interface Trimable

validateOrder

public void validateOrder()

Re-orders the cells into a proper order (if they aren't already).