hongshaorou/openrocket
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

adds documentation to some document package and rocketcomponents

Browse Source
This commit is contained in:
Luiz Victor Linhares Rocha 2016-10-19 15:22:28 -02:00
parent b708520364
commit 9f10b8cec1
6 changed files with 392 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
core/src/net/sf/openrocket/document/Attachment.java
View File

@ -18,7 +18,7 @@ public abstract class Attachment extends AbstractChangeSource implements Compara
/**
* default constructor
* @param name the name of attachment
* @param name the attachment name
*/
public Attachment(String name) {
super();
@ -41,6 +41,10 @@ public abstract class Attachment extends AbstractChangeSource implements Compara
*/
public abstract InputStream getBytes() throws FileNotFoundException, IOException;
/**
* {@inheritDoc}
* considers only the name to equals
*/
@Override
public int compareTo(Attachment o) {
return this.name.compareTo(o.name);

92
core/src/net/sf/openrocket/document/DecalRegistry.java
View File

@ -33,7 +33,7 @@ import net.sf.openrocket.util.StateChangeListener;
public class DecalRegistry {
/**
* default constructor
* default constructor, does nothing
*/
DecalRegistry() {
}
@ -41,6 +41,12 @@ public class DecalRegistry {
/** the decal usage map*/
private Map<String, DecalImageImpl> registeredDecals = new HashMap<String, DecalImageImpl>();
/**
* returns a new decal with the same image but with unique names
* supports only classes and subclasses of DecalImageImpl
* @param original the decal to be made unique
* @return
*/
public DecalImage makeUniqueImage(DecalImage original) {
if (!(original instanceof DecalImageImpl)) {
@ -66,6 +72,11 @@ public class DecalRegistry {
}
/**
* get the image from an attachment
* @param attachment
* @return
*/
public DecalImage getDecalImage(Attachment attachment) {
String decalName = attachment.getName();
DecalImageImpl d;
@ -175,6 +186,10 @@ public class DecalRegistry {
}
}
/**
*
* @return
*/
File getFileSystemLocation() {
return fileSystemLocation;
}
@ -214,6 +229,11 @@ public class DecalRegistry {
}
/**
* sercha
* @param file
* @return
*/
private DecalImageImpl findDecalForFile(File file) {
for (DecalImageImpl d : registeredDecals.values()) {
@ -249,28 +269,25 @@ public class DecalRegistry {
private static final int NUMBER_INDEX = 3;
private static final int EXTENSION_INDEX = 4;
/**
* Makes a unique name for saving decal files in case the name already exists
* @param name the name of the decal
* @return the name formated and unique
*/
private String makeUniqueName(String name) {
String newName = name;
if (!newName.startsWith("decals/")) {
newName = "decals/" + name;
}
String basename = "";
String extension = "";
Matcher nameMatcher = fileNamePattern.matcher(newName);
if (nameMatcher.matches()) {
basename = nameMatcher.group(BASE_NAME_INDEX);
extension = nameMatcher.group(EXTENSION_INDEX);
}
String newName = checkPathConsistency(name);
String basename = getGroup(BASE_NAME_INDEX,fileNamePattern.matcher(newName));
String extension = getGroup(EXTENSION_INDEX,fileNamePattern.matcher(newName));
Set<Integer> counts = new TreeSet<Integer>();
boolean needsRewrite = false;
for (DecalImageImpl d : registeredDecals.values()) {
Matcher m = fileNamePattern.matcher(d.getName());
if (m.matches()) {
if (basename.equals(m.group(BASE_NAME_INDEX)) && extension.equals(m.group(EXTENSION_INDEX))) {
if (isofSameBaseAndExtension(m, basename, extension)) {
String intString = m.group(NUMBER_INDEX);
if (intString != null) {
Integer i = Integer.parseInt(intString);
@ -287,13 +304,54 @@ public class DecalRegistry {
return newName;
}
// find a missing integer;
return MessageFormat.format("{0} ({1}).{2}", basename, findMissingInteger(counts),extension);
}
/**
* Searches the count for a new Integer
* @param counts the count set
* @return a unique integer in the count
*/
private Integer findMissingInteger(Set<Integer> counts) {
Integer newIndex = 1;
while (counts.contains(newIndex)) {
newIndex++;
}
return MessageFormat.format("{0} ({1}).{2}", basename, newIndex, extension);
return newIndex;
}
/**
* Tests if a matcher has the same basename and extension
* @param m the matcher being tested
* @param basename the basename
* @param extension the extension
* @return
*/
private boolean isofSameBaseAndExtension(Matcher m, String basename, String extension) {
return basename.equals(m.group(BASE_NAME_INDEX)) && extension.equals(m.group(EXTENSION_INDEX));
}
/**
* gets the String group from a matcher
* @param index the index of the group to
* @param matcher the matcher for the search
* @return the String according with the group, empty if there's no match
*/
private String getGroup(int index, Matcher matcher) {
if (matcher.matches())
return matcher.group(index);
return "";
}
/**
* checks if the name starts with "decals/"
* @param name the name being checked
* @return the name complete with the starting folder
*/
private String checkPathConsistency(String name){
if (name.startsWith("decals/"))
return name;
return "decals/" + name;
}
}

283
core/src/net/sf/openrocket/document/OpenRocketDocument.java
View File

@ -102,36 +102,56 @@ public class OpenRocketDocument implements ComponentChangeListener {
private final List<DocumentChangeListener> listeners = new ArrayList<DocumentChangeListener>();
/**
* main constructor, enable events in the rocket
* and initializes the document
* @param rocket the rocket to be used in the document
*/
OpenRocketDocument(Rocket rocket) {
this.rocket = rocket;
rocket.enableEvents();
init();
}
/**
* initializes the document, clearing the undo cache and
* setting itself as a listener for changes in the rocket
*/
private void init() {
clearUndo();
rocket.addComponentChangeListener(this);
}
/**
* adds a customExpression into the list
* @param expression the expression to be added
*/
public void addCustomExpression(CustomExpression expression) {
if (customExpressions.contains(expression)) {
log.info(Markers.USER_MARKER, "Could not add custom expression " + expression.getName() + " to document as document alerady has a matching expression.");
} else {
customExpressions.add(expression);
}
}
customExpressions.add(expression);
}
/**
* remves
* @param expression
*/
public void removeCustomExpression(CustomExpression expression) {
customExpressions.remove(expression);
}
//TODO:LOW:this leaves the object custom expression exposed, is it supposed to be like that?
/**
*
* @return
*/
public List<CustomExpression> getCustomExpressions() {
return customExpressions;
}
/*
* Returns a set of all the flight data types defined or available in any way in the rocket document
/**
* @returns a set of all the flight data types defined or available in any way in the rocket document
*/
public Set<FlightDataType> getFlightDataTypes() {
Set<FlightDataType> allTypes = new LinkedHashSet<FlightDataType>();
@ -158,28 +178,50 @@ public class OpenRocketDocument implements ComponentChangeListener {
return allTypes;
}
/**
* gets the rocket in the document
* @return the rocket in the document
*/
public Rocket getRocket() {
return rocket;
}
/**
* returns the selected configuration from the rocket
* @return selected configuration from the rocket
*/
public FlightConfiguration getSelectedConfiguration() {
return rocket.getSelectedConfiguration();
}
/**
* returns the File handler object for the document
* @return the File handler object for the document
*/
public File getFile() {
return file;
}
/**
* set the file handler object for the document
* @param file the new file handler object
*/
public void setFile(File file) {
this.file = file;
}
/**
* returns if the current rocket is saved
* @return if the current rocket is saved
*/
public boolean isSaved() {
return rocket.getModID() == savedID;
}
/**
* sets the current rocket as saved, and none if false is given
* @param saved if the current rocket or none will be set to save
*/
public void setSaved(boolean saved) {
if (saved == false)
this.savedID = -1;
@ -197,33 +239,57 @@ public class OpenRocketDocument implements ComponentChangeListener {
}
/**
* returns the decal list used in the document
* @return the decal list registered in the document
*/
public Collection<DecalImage> getDecalList() {
return decalRegistry.getDecalList();
}
/**
* returns the number of times the given decal was used
* @param img the decal to be counted
* @return the number of times
*/
public int countDecalUsage(DecalImage img) {
int count = 0;
Iterator<RocketComponent> it = rocket.iterator();
while (it.hasNext()) {
RocketComponent comp = it.next();
Appearance a = comp.getAppearance();
if (a == null) {
continue;
}
Decal d = a.getTexture();
if (d == null) {
continue;
}
if (img.equals(d.getImage())) {
if(hasDecal(it.next(),img))
count++;
}
}
return count;
}
//TODO: LOW: move this method to rocketComponent, Appearance and decal
//I see 3 layers of object accessed, seems unsafe
/**
* checks if a rocket component has the given decalImage
* @param comp the RocketComponent to be searched
* @param img the DecalImage to be checked
* @return if the comp has img
*/
private boolean hasDecal(RocketComponent comp, DecalImage img){
Appearance a = comp.getAppearance();
if(a == null)
return false;
Decal d = a.getTexture();
if(d == null)
return false;
if(img.equals(d.getImage()))
return true;
return false;
}
/**
* gets a unique identification for the given decal
* @param img the decal to be made unique
* @return the new unique decal
*/
public DecalImage makeUniqueDecal(DecalImage img) {
if (countDecalUsage(img) <= 1) {
return img;
@ -231,26 +297,54 @@ public class OpenRocketDocument implements ComponentChangeListener {
return decalRegistry.makeUniqueImage(img);
}
/**
* gets the decal image from an attachment
* @param a the attachment
* @return the image from the attachment
*/
public DecalImage getDecalImage(Attachment a) {
return decalRegistry.getDecalImage(a);
}
/**
* gets a list of simulations in the document
* @return the simulations in the document
*/
public List<Simulation> getSimulations() {
return simulations.clone();
}
/**
* gets the number of simulations in the document
* @return the number of simulations in the document
*/
public int getSimulationCount() {
return simulations.size();
}
/**
* the the Nth simulation from the document
* @param n simulation index
* @return the Nth simulation from the document, null if there's none
*/
public Simulation getSimulation(int n) {
return simulations.get(n);
}
/**
* gets the index of the given simulation
* @param simulation the simulation being searched
* @return the index of the simulation in the document
*/
public int getSimulationIndex(Simulation simulation) {
return simulations.indexOf(simulation);
}
/**
* adds simulation into the document
* fires document change event
* @param simulation the simulation to be added
*/
public void addSimulation(Simulation simulation) {
simulations.add(simulation);
FlightConfigurationId simId = simulation.getId();
@ -260,33 +354,61 @@ public class OpenRocketDocument implements ComponentChangeListener {
fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
}
/**
* adds the simulation to the Nth index, overwriting if there is already one
* fires change document event
* @param simulation the simulation to be added
* @param n the index to be added
*/
public void addSimulation(Simulation simulation, int n) {
simulations.add(n, simulation);
fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
}
/**
* removes the specific simulation from the list
* @param simulation the simulation to be removed
*/
public void removeSimulation(Simulation simulation) {
simulations.remove(simulation);
fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
}
/**
* removes the Nth simulation from the document
* fires document change event
* @param n the Nth simulation
* @return the removed simulation
*/
public Simulation removeSimulation(int n) {
Simulation simulation = simulations.remove(n);
fireDocumentChangeEvent(new SimulationChangeEvent(simulation));
return simulation;
}
/**
* removes the flight configuration and simulation with the specific id
* @param configId
*/
public void removeFlightConfigurationAndSimulations(FlightConfigurationId configId) {
if (configId == null) {
return;
}
removeSimulations(configId);
rocket.removeFlightConfiguration(configId);
}
/**
* removes all simulations with the specific configId
* @param configId the Flight Configuration Id that dictates which simulations shoul be removed
*/
private void removeSimulations(FlightConfigurationId configId) {
for (Simulation s : getSimulations()) {
// Assumes modifiable collection - which it is
if (configId.equals(s.getId())) {
removeSimulation(s);
}
}
rocket.removeFlightConfiguration(configId);
}
@ -331,42 +453,22 @@ public class OpenRocketDocument implements ComponentChangeListener {
*/
public void addUndoPosition(String description) {
if (storedDescription != null) {
logUndoError("addUndoPosition called while storedDescription=" + storedDescription +
" description=" + description);
}
checkDescription(description);
// Check whether modifications have been done since last call
if (isCleanState()) {
// No modifications
log.info("Adding undo position '" + description + "' to " + this + ", document was in clean state");
nextDescription = description;
if(isCheckNoModification(description))
return;
}
log.info("Adding undo position '" + description + "' to " + this + ", document is in unclean state");
checkUndoPositionConsistency();
addStateToUndoHistory(description);
/*
* Modifications have been made to the rocket. We should be at the end of the
* undo history, but check for consistency and try to recover.
*/
if (undoPosition != undoHistory.size() - 1) {
logUndoError("undo position inconsistency");
}
while (undoPosition < undoHistory.size() - 1) {
undoHistory.removeLast();
undoDescription.removeLast();
}
// Add the current state to the undo history
undoHistory.add(rocket.copyWithOriginalID());
undoDescription.add(null);
nextDescription = description;
undoPosition++;
// Maintain maximum undo size
maintainMaximumUndoSize();
}
/**
*
*/
private void maintainMaximumUndoSize() {
if (undoHistory.size() > UNDO_LEVELS + UNDO_MARGIN && undoPosition > UNDO_MARGIN) {
for (int i = 0; i < UNDO_MARGIN; i++) {
undoHistory.removeFirst();
@ -375,6 +477,57 @@ public class OpenRocketDocument implements ComponentChangeListener {
}
}
}
/**
* @param description
*/
private void addStateToUndoHistory(String description) {
// Add the current state to the undo history
undoHistory.add(rocket.copyWithOriginalID());
undoDescription.add(null);
nextDescription = description;
undoPosition++;
}
/**
* checks if there was or not modification, and logs
*
* @param description the description to be used in the log
* @return if there was or not modification
*/
private boolean isCheckNoModification(String description){
if (isCleanState()) {
// No modifications
log.info("Adding undo position '" + description + "' to " + this + ", document was in clean state");
nextDescription = description;
return true;
}
return false;
}
/**
* checks if the document already has a stored undo description
* logs if it has
*
* @param description undo description to be logged
*/
private void checkDescription(String description) {
if (storedDescription != null) {
logUndoError("addUndoPosition called while storedDescription=" + storedDescription +
" description=" + description);
}
}
/**
* If modifications have been made to the rocket. We should be at the end of the
* undo history, but check for consistency and try to recover.
*/
private void checkUndoPositionConsistency() {
if (undoPosition != undoHistory.size() - 1) {
logUndoError("undo position inconsistency");
}
removeRedoInfo();
}
/**
@ -436,18 +589,29 @@ public class OpenRocketDocument implements ComponentChangeListener {
" undoPosition=" + undoPosition + " undoHistory.size=" + undoHistory.size() +
" isClean=" + isCleanState());
}
// Remove any redo information if available
while (undoPosition < undoHistory.size() - 1) {
undoHistory.removeLast();
undoDescription.removeLast();
}
// Set the latest description
undoDescription.set(undoPosition, nextDescription);
removeRedoInfo();
setLatestDescription();
}
fireUndoRedoChangeEvent();
}
/**
* Sets the latest description
*/
private void setLatestDescription() {
undoDescription.set(undoPosition, nextDescription);
}
/**
* Removes any redo information if available
*/
private void removeRedoInfo() {
while (undoPosition < undoHistory.size() - 1) {
undoHistory.removeLast();
undoDescription.removeLast();
}
}
/**
@ -610,6 +774,7 @@ public class OpenRocketDocument implements ComponentChangeListener {
undoRedoListeners.remove(listener);
}
private void fireUndoRedoChangeEvent() {
UndoRedoListener[] array = undoRedoListeners.toArray(new UndoRedoListener[0]);
for (UndoRedoListener l : array) {

21
core/src/net/sf/openrocket/document/attachments/FileSystemAttachment.java
View File

@ -8,19 +8,38 @@ import java.io.InputStream;
import net.sf.openrocket.document.Attachment;
/**
*
* defines a file system attachment
* stores the attachment location
*/
public class FileSystemAttachment extends Attachment {
/** the file location*/
private final File location;
/**
* main constructor,
*
* @param name name of attachment
* @param location File location of attachment
*/
public FileSystemAttachment(String name, File location) {
super(name);
this.location = location;
}
/**
*
* @return the File object with the attachment location
*/
public File getLocation() {
return location;
}
/**
* {@inheritDoc}
* creates the stream based on the location passed while building
*/
@Override
public InputStream getBytes() throws FileNotFoundException, IOException {
return new FileInputStream(location);

66
core/src/net/sf/openrocket/rocketcomponent/FlightConfigurationId.java
View File

@ -2,7 +2,7 @@ package net.sf.openrocket.rocketcomponent;
import java.util.UUID;
/*
/**
* FlightConfigurationID is a very minimal wrapper class used to identify a given flight configuration for various components and options.
* It is intended to provide better visibility and traceability by more specific type safety -- this class replaces a
* straight-up <code>String</code> Key in previous implementations.
@ -19,10 +19,17 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
public final static FlightConfigurationId ERROR_FCID = new FlightConfigurationId( FlightConfigurationId.ERROR_UUID);
public final static FlightConfigurationId DEFAULT_VALUE_FCID = new FlightConfigurationId( FlightConfigurationId.DEFAULT_VALUE_UUID );
/**
* default constructor, builds with an unique random ID
*/
public FlightConfigurationId() {
this(UUID.randomUUID());
}
/**
* builds the id with the given String
* @param _str te string to be made into the id
*/
public FlightConfigurationId(final String _str) {
UUID candidate;
if(_str == null || "".equals(_str)){
@ -37,6 +44,10 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
this.key = candidate;
}
/**
* builds he id with the given UUID object
* @param _val the UUID to be made into the id
*/
public FlightConfigurationId(final UUID _val) {
if (null == _val){
this.key = FlightConfigurationId.ERROR_UUID;
@ -45,6 +56,10 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
}
}
/**
* {@inheritDoc}
* considers equals ids with the same key
*/
@Override
public boolean equals(Object anObject) {
if (!(anObject instanceof FlightConfigurationId)) {
@ -55,32 +70,65 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
return this.key.equals(otherFCID.key);
}
/**
*
* @return
*/
public String toShortKey(){
if( hasError() ){
if( hasError() )
return FlightConfigurationId.ERROR_KEY_NAME;
}else if( this.key == FlightConfigurationId.DEFAULT_VALUE_UUID){
if( isDefaultId())
return FlightConfigurationId.DEFAULT_VALUE_NAME;
}else{
return this.key.toString().substring(0,8);
}
return this.key.toString().substring(0,8);
}
//extracted this method because maybe, just maybe, this info could be used somewhere else
/**
* gets if the id is the default
* @return if the id is default
*/
private boolean isDefaultId() {
return this.key == FlightConfigurationId.DEFAULT_VALUE_UUID;
}
/**
* returns the whole key in the id
* @return the full key of the id
*/
public String toFullKey(){
return this.key.toString();
return this.toString();
}
/**
* {@inheritDoc}
* uses the key hash code
*/
@Override
public int hashCode() {
return this.key.hashCode();
}
/**
* checks if the key is the ERROR_UUID flag
* @return if the id has error
*/
public boolean hasError(){
return (ERROR_UUID == this.key);
}
/**
* checks if the key from the id is valid
* @return if the id is valid or not
*/
public boolean isValid() {
return !hasError();
}
/**
* {@inheritDoc}
* same as get full id
*/
@Override
public String toString() {
return this.key.toString();
@ -91,6 +139,10 @@ public final class FlightConfigurationId implements Comparable<FlightConfigurati
return this.key.compareTo( other.key);
}
/**
* used for debuggin, gets the short key
* @return the short key version of the id
*/
public String toDebug(){
return this.toShortKey();
}

9
core/src/net/sf/openrocket/rocketcomponent/RocketComponent.java
View File

@ -355,6 +355,10 @@ public abstract class RocketComponent implements ChangeSource, Cloneable, Iterab
}
}
/**
* appends the debug string of the component into the passed builder
* @param sb String builder to be appended
*/
private void toDebugString(StringBuilder sb) {
sb.append(this.getClass().getSimpleName()).append('@').append(System.identityHashCode(this));
sb.append("[\"").append(this.getName()).append('"');
@ -962,6 +966,10 @@ public abstract class RocketComponent implements ChangeSource, Cloneable, Iterab
return result;
}
/**
* returns the axial offset of the component
* @return
*/
public double getAxialOffset() {
mutex.verify();
return this.asPositionValue(this.relativePosition);
@ -2085,6 +2093,7 @@ public abstract class RocketComponent implements ChangeSource, Cloneable, Iterab
}
}
/// debug functions
public String toDebugName(){
return this.getName()+"<"+this.getClass().getSimpleName()+">("+this.getID().substring(0,8)+")";
}