Permalink
Browse files

lots of javadoc improvements

Signed-off-by: gburgett <gordon.burgett@gmail.com>
  • Loading branch information...
1 parent 58bad56 commit 1dd47cb888863979e501b33508d387384ff697fb @gburgett committed Jan 29, 2013
Showing with 1,104 additions and 297 deletions.
  1. +15 −2 java/XFlat/nbproject/project.properties
  2. +15 −4 java/XFlat/src/org/jdom2/jaxb/package-info.java
  3. +6 −1 java/XFlat/src/org/xflatdb/xflat/convert/DefaultConversionService.java
  4. +3 −4 java/XFlat/src/org/xflatdb/xflat/convert/converters/JDOMConverters.java
  5. +22 −0 java/XFlat/src/org/xflatdb/xflat/convert/converters/package-info.java
  6. +18 −1 java/XFlat/src/org/xflatdb/xflat/db/EngineBase.java
  7. +32 −2 java/XFlat/src/org/xflatdb/xflat/db/EngineState.java
  8. +12 −2 java/XFlat/src/org/xflatdb/xflat/db/IntegerIdGenerator.java
  9. +55 −10 java/XFlat/src/org/xflatdb/xflat/db/ShardedEngineBase.java
  10. +26 −3 java/XFlat/src/org/xflatdb/xflat/db/TableBase.java
  11. +24 −5 java/XFlat/src/org/xflatdb/xflat/db/TableMetadataFactory.java
  12. +36 −6 java/XFlat/src/org/xflatdb/xflat/db/XFlatDatabase.java
  13. +34 −46 java/XFlat/src/org/xflatdb/xflat/engine/CachedDocumentEngine.java
  14. +9 −1 java/XFlat/src/org/xflatdb/xflat/engine/DefaultEngineFactory.java
  15. +14 −4 java/XFlat/src/org/xflatdb/xflat/engine/IdShardedEngine.java
  16. +3 −2 java/XFlat/src/org/xflatdb/xflat/engine/InactiveCache.java
  17. +6 −1 java/XFlat/src/org/xflatdb/xflat/query/EmptyCursor.java
  18. +6 −1 java/XFlat/src/org/xflatdb/xflat/query/Interval.java
  19. +2 −1 java/XFlat/src/org/xflatdb/xflat/query/IntervalComparator.java
  20. +19 −13 java/XFlat/src/org/xflatdb/xflat/query/IntervalProvider.java
  21. +28 −14 java/XFlat/src/org/xflatdb/xflat/query/IntervalSet.java
  22. +8 −1 java/XFlat/src/org/xflatdb/xflat/query/InvalidQueryException.java
  23. +17 −18 java/XFlat/src/org/xflatdb/xflat/query/NumericIntervalProvider.java
  24. +27 −5 java/XFlat/src/org/xflatdb/xflat/query/XPathQuery.java
  25. +32 −10 java/XFlat/src/org/xflatdb/xflat/query/XPathUpdate.java
  26. +22 −0 java/XFlat/src/org/xflatdb/xflat/query/package-info.java
  27. +1 −1 java/XFlat/src/org/xflatdb/xflat/transaction/Isolation.java
  28. +39 −5 java/XFlat/src/org/xflatdb/xflat/transaction/ThreadContextTransactionManager.java
  29. +25 −12 java/XFlat/src/org/xflatdb/xflat/transaction/Transaction.java
  30. +1 −1 java/XFlat/src/org/xflatdb/xflat/transaction/TransactionException.java
  31. +2 −1 java/XFlat/src/org/xflatdb/xflat/transaction/TransactionListener.java
  32. +7 −4 java/XFlat/src/org/xflatdb/xflat/transaction/TransactionManager.java
  33. +27 −5 java/XFlat/src/org/xflatdb/xflat/transaction/TransactionOptions.java
  34. +3 −2 java/XFlat/src/org/xflatdb/xflat/transaction/WriteConflictException.java
  35. +21 −0 java/XFlat/src/org/xflatdb/xflat/transaction/package-info.java
  36. +42 −0 java/XFlat/src/org/xflatdb/xflat/util/DocumentFileWrapper.java
  37. +19 −4 java/XFlat/src/org/xflatdb/xflat/util/XPathExpressionEqualityMatcher.java
  38. +20 −0 java/XFlat/src/org/xflatdb/xflat/util/package-info.java
  39. +15 −2 java/XFlat/test/commons-logging.properties
  40. +16 −5 java/XFlat/test/org/xflatdb/xflat/convert/DefaultConversionServiceTest.java
  41. +15 −4 java/XFlat/test/org/xflatdb/xflat/convert/converters/JAXBPojoConverterTest.java
  42. +15 −4 java/XFlat/test/org/xflatdb/xflat/db/ConvertingTableTest.java
  43. +15 −4 java/XFlat/test/org/xflatdb/xflat/db/DatabaseIntegrationTest.java
  44. +15 −4 java/XFlat/test/org/xflatdb/xflat/db/ElementTableTest.java
  45. +15 −4 java/XFlat/test/org/xflatdb/xflat/db/EngineTestsBase.java
  46. +15 −4 java/XFlat/test/org/xflatdb/xflat/db/EngineTransactionManagerTestBase.java
  47. +15 −4 java/XFlat/test/org/xflatdb/xflat/db/ShardedEngineTestsBase.java
  48. +15 −4 java/XFlat/test/org/xflatdb/xflat/db/XFlatDatabaseTest.java
  49. +15 −4 java/XFlat/test/org/xflatdb/xflat/engine/CachedDocumentEngineTest.java
  50. +15 −4 java/XFlat/test/org/xflatdb/xflat/engine/IdShardedEngineIntegrationTests.java
  51. +15 −4 java/XFlat/test/org/xflatdb/xflat/engine/IdShardedEngineTest.java
  52. +15 −4 java/XFlat/test/org/xflatdb/xflat/query/IntervalSetTest.java
  53. +15 −4 java/XFlat/test/org/xflatdb/xflat/query/NumericIntervalProviderTest.java
  54. +15 −4 java/XFlat/test/org/xflatdb/xflat/query/XPathQueryTest.java
  55. +15 −4 java/XFlat/test/org/xflatdb/xflat/query/XPathUpdateTest.java
  56. +15 −4 java/XFlat/test/org/xflatdb/xflat/transaction/FakeThreadContextTransactionManager.java
  57. +15 −4 java/XFlat/test/org/xflatdb/xflat/transaction/ThreadContextTransactionManagerTest.java
  58. +15 −4 java/XFlat/test/org/xflatdb/xflat/util/FakeDocumentFileWrapper.java
  59. +15 −4 java/XFlat/test/org/xflatdb/xflat/util/XPathExpressionEqualityMatcherTest.java
  60. +15 −2 java/XFlat/test/simplelog.properties
  61. +15 −4 java/XFlat/test/test/Bar.java
  62. +15 −4 java/XFlat/test/test/Baz.java
  63. +15 −4 java/XFlat/test/test/Foo.java
  64. +15 −4 java/XFlat/test/test/SubFoo.java
  65. +15 −4 java/XFlat/test/test/Utils.java
@@ -1,9 +1,10 @@
annotation.processing.enabled=true
annotation.processing.enabled.in.editor=false
-annotation.processing.processor.options=
annotation.processing.processors.list=
annotation.processing.run.all.processors=true
annotation.processing.source.output=${build.generated.sources.dir}/ap-source-output
+application.title=XFlat
+application.vendor=Gordon
build.classes.dir=${build.dir}/classes
build.classes.excludes=**/*.java,**/*.form
# This directory is removed when the project is cleaned:
@@ -24,9 +25,12 @@ debug.test.classpath=\
dist.dir=dist
dist.jar=${dist.dir}/XFlat.jar
dist.javadoc.dir=${dist.dir}/javadoc
+endorsed.classpath=
excludes=
includes=**
-jar.compress=false
+jar.archive.disabled=${jnlp.enabled}
+jar.compress=true
+jar.index=${jnlp.enabled}
javac.classpath=\
${libs.Apache_Commons_Logging.classpath}:\
${libs.Hamcrest_Matchers.classpath}:\
@@ -58,6 +62,15 @@ javadoc.splitindex=true
javadoc.use=true
javadoc.version=false
javadoc.windowtitle=
+jnlp.codebase.type=no.codebase
+jnlp.descriptor=application
+jnlp.enabled=false
+jnlp.mixed.code=default
+jnlp.offline-allowed=false
+jnlp.signed=false
+jnlp.signing=
+jnlp.signing.alias=
+jnlp.signing.keystore=
meta.inf.dir=${src.dir}/META-INF
mkdist.disabled=true
platform.active=default_platform
@@ -1,7 +1,18 @@
-/*
- * To change this template, choose Tools | Templates
- * and open the template in the editor.
- */
+/*
+* Copyright 2013 Gordon Burgett and individual contributors
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
/**
* This package contains experimental classes from the JDOM development branch
@@ -21,7 +21,9 @@
import java.util.concurrent.locks.ReentrantReadWriteLock;
/**
- *
+ * The default implementation of {@link ConversionService}. This conversion
+ * service manages a mapping of conversions to their converters, and can perform
+ * no conversions initially.
* @author gordon
*/
public class DefaultConversionService implements ConversionService {
@@ -30,6 +32,9 @@
private ReadWriteLock converterLock = new ReentrantReadWriteLock();
+ /**
+ * Creates a new DefaultConversionService with no registered conversions.
+ */
public DefaultConversionService(){
}
@@ -15,19 +15,18 @@
*/
package org.xflatdb.xflat.convert.converters;
-import org.xflatdb.xflat.convert.ConversionException;
+import org.jdom2.*;
import org.xflatdb.xflat.convert.ConversionService;
import org.xflatdb.xflat.convert.Converter;
-import org.jdom2.*;
/**
- *
+ * A number of converters that converts JDOM values to and from several types.
* @author gordon
*/
public class JDOMConverters {
/**
- * Registers all the string converters to the given ConversionService.
+ * Registers all the JDOM converters to the given ConversionService.
* @param service
*/
public static void registerTo(ConversionService service){
@@ -0,0 +1,22 @@
+/*
+* Copyright 2013 Gordon Burgett and individual contributors
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+/**
+ * This package contains basic converters implemented for common conversion
+ * types. The converters in this package focus on converting to and from
+ * {@link org.jdom2.Element}.
+ */
+package org.xflatdb.xflat.convert.converters;
@@ -26,14 +26,14 @@
import java.util.concurrent.atomic.AtomicReference;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
+import org.jdom2.Element;
import org.xflatdb.xflat.EngineStateException;
import org.xflatdb.xflat.XFlatException;
import org.xflatdb.xflat.convert.ConversionService;
import org.xflatdb.xflat.db.EngineBase.RowData;
import org.xflatdb.xflat.transaction.Transaction;
import org.xflatdb.xflat.transaction.TransactionException;
import org.xflatdb.xflat.transaction.TransactionManager;
-import org.jdom2.Element;
/**
* The base class for Engine objects. The Database uses the functionality
@@ -125,6 +125,10 @@ protected void setLastActivity(long time){
}while(!lastActivity.compareAndSet(existing, time));
}
+ /**
+ * An event handler for the events fired when an Engine finishes spinning
+ * down.
+ */
public static interface SpinDownEventHandler{
/**
* Called when the engine is completely finished spinning down,
@@ -134,12 +138,25 @@ protected void setLastActivity(long time){
public void spinDownComplete(SpinDownEvent event);
}
+ /**
+ * An event object given to the {@link SpinDownEventHandler} when an
+ * engine finishes spinning down.
+ */
public static class SpinDownEvent extends java.util.EventObject{
+ /**
+ * The Engine that has spun down.
+ * @return
+ */
@Override
public Engine getSource(){
return (Engine)super.getSource();
}
+ /**
+ * Creates a new SpinDownEvent which says the given engine has finished
+ * spinning down.
+ * @param source The engine which has finished spinning down.
+ */
public SpinDownEvent(Engine source){
super(source);
}
@@ -5,10 +5,40 @@
package org.xflatdb.xflat.db;
/**
- *
+ * Represents the progression of states in an engine as it is used.
* @author Gordon
*/
public enum EngineState {
- Uninitialized, SpinningUp, SpunUp, Running, SpinningDown, SpunDown
+ /**
+ * The state of a newly instantiated engine, before it is ready.
+ * Any operations on this engine will throw.
+ */
+ Uninitialized,
+ /**
+ * The state of an engine that is in the process of initializing.
+ * At this point the engine can obtain a read-lock on the underlying data.
+ */
+ SpinningUp,
+ /**
+ * The state of an engine that has finished initializing and is waiting
+ * to be notified that it can have sole access to the underlying data.
+ */
+ SpunUp,
+ /**
+ * The state of an engine that has a write lock and sole access to the underlying
+ * data store.
+ */
+ Running,
+ /**
+ * The state of an engine that is in the process of shutting down.
+ * At this point the engine releases its write lock and only responds to
+ * read requests from outstanding cursors.
+ */
+ SpinningDown,
+ /**
+ * The state of an engine that has finished shutting down and is no longer
+ * expecting even read operations. Any operations on this engine will throw.
+ */
+ SpunDown
}
@@ -19,7 +19,9 @@
import org.jdom2.Element;
/**
- *
+ * An IdGenerator which generates incrementing integer IDs. This ID generator
+ * supports {@link Integer}, {@link Float}, {@link Double}, {@link Long}, and
+ * {@link String} IDs.
* @author gordon
*/
public class IntegerIdGenerator extends IdGenerator {
@@ -116,12 +118,20 @@ public Object stringToId(String id, Class<?> idType) {
throw new UnsupportedOperationException("Unsupported ID type " + idType);
}
-
+ /**
+ * Saves the maximum ID generated by this Id generator, so that it can resume
+ * when reloaded.
+ * @param state The state object to which the maximum Id is saved.
+ */
@Override
public void saveState(Element state){
state.setAttribute("maxId", Integer.toString(this.lastId.get()), XFlatDatabase.xFlatNs);
}
+ /**
+ * Loads the maximum Id into this ID generator so that it can resume generating IDs.
+ * @param state The state object containing the maximum ID already generated.
+ */
@Override
public void loadState(Element state){
String maxId = state.getAttributeValue("maxId", XFlatDatabase.xFlatNs);
Oops, something went wrong. Retry.

0 comments on commit 1dd47cb

Please sign in to comment.