diff --git a/.idea/ant.xml b/.idea/ant.xml deleted file mode 100644 index 4fa7e1336a..0000000000 --- a/.idea/ant.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/.idea/codeStyleSettings.xml b/.idea/codeStyleSettings.xml deleted file mode 100644 index 9fafc3a169..0000000000 --- a/.idea/codeStyleSettings.xml +++ /dev/null @@ -1,227 +0,0 @@ - - - - - - \ No newline at end of file diff --git a/.idea/compiler.xml b/.idea/compiler.xml deleted file mode 100644 index 8f39e62170..0000000000 --- a/.idea/compiler.xml +++ /dev/null @@ -1,48 +0,0 @@ - - - - - - - - - - diff --git a/.idea/copyright/NASA.xml b/.idea/copyright/NASA.xml deleted file mode 100644 index e79c3d8d36..0000000000 --- a/.idea/copyright/NASA.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/copyright/profiles_settings.xml b/.idea/copyright/profiles_settings.xml deleted file mode 100644 index b7f9bb2497..0000000000 --- a/.idea/copyright/profiles_settings.xml +++ /dev/null @@ -1,7 +0,0 @@ - - - - - - - \ No newline at end of file diff --git a/.idea/encodings.xml b/.idea/encodings.xml deleted file mode 100644 index e206d70d85..0000000000 --- a/.idea/encodings.xml +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml deleted file mode 100644 index 90eca5898e..0000000000 --- a/.idea/inspectionProfiles/Project_Default.xml +++ /dev/null @@ -1,23 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/inspectionProfiles/profiles_settings.xml b/.idea/inspectionProfiles/profiles_settings.xml deleted file mode 100644 index 44eb48c62a..0000000000 --- a/.idea/inspectionProfiles/profiles_settings.xml +++ /dev/null @@ -1,15 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/libraries/gdal.xml b/.idea/libraries/gdal.xml deleted file mode 100644 index 89f743f896..0000000000 --- a/.idea/libraries/gdal.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - \ No newline at end of file diff --git a/.idea/libraries/jogl.xml b/.idea/libraries/jogl.xml deleted file mode 100644 index efa4e85d84..0000000000 --- a/.idea/libraries/jogl.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - \ No newline at end of file diff --git a/.idea/libraries/junit4.xml b/.idea/libraries/junit4.xml deleted file mode 100644 index 73b6283c49..0000000000 --- a/.idea/libraries/junit4.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml deleted file mode 100644 index 3eaa6828eb..0000000000 --- a/.idea/misc.xml +++ /dev/null @@ -1,69 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - http://www.w3.org/1999/xhtml - - - - - - \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml deleted file mode 100644 index d9e337b55a..0000000000 --- a/.idea/modules.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/.idea/projectCodeStyle.xml b/.idea/projectCodeStyle.xml deleted file mode 100644 index 21c32ccf3e..0000000000 --- a/.idea/projectCodeStyle.xml +++ /dev/null @@ -1,202 +0,0 @@ - - - - - - - diff --git a/.idea/runConfigurations/ApplicationTemplate.xml b/.idea/runConfigurations/ApplicationTemplate.xml deleted file mode 100644 index 714b6ea73e..0000000000 --- a/.idea/runConfigurations/ApplicationTemplate.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/runConfigurations/KMLViewer.xml b/.idea/runConfigurations/KMLViewer.xml deleted file mode 100644 index 79fa526268..0000000000 --- a/.idea/runConfigurations/KMLViewer.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/runConfigurations/WMSLayerManager.xml b/.idea/runConfigurations/WMSLayerManager.xml deleted file mode 100644 index 039dbcede8..0000000000 --- a/.idea/runConfigurations/WMSLayerManager.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - - - \ No newline at end of file diff --git a/.idea/scopes/scope_settings.xml b/.idea/scopes/scope_settings.xml deleted file mode 100644 index 922003b843..0000000000 --- a/.idea/scopes/scope_settings.xml +++ /dev/null @@ -1,5 +0,0 @@ - - - - \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml deleted file mode 100644 index 275077f825..0000000000 --- a/.idea/vcs.xml +++ /dev/null @@ -1,7 +0,0 @@ - - - - - - - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 374f04ef67..b544c7879d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,8 +17,7 @@ **Please do not file an issue to ask a question.** You will get faster results by using the following resources: -- Check out the [WorldWind Forum](https://forum.worldwindcentral.com/) -- Email the [Administrative Contact](mailto:patrick.hogan@nasa.gov) +- Email the [Administrative Contact](mailto:worldwind-info@lists.nasa.gov) ## Design and Coding Guidelines @@ -27,9 +26,9 @@ WorldWind projects. ### General -* The project's development IDE is IntelliJ IDEA. The IDEA configuration files for this project are checked in to +* The project's development IDE is Apache NetBeans. The NetBeans configuration files for this project are checked in to the code repository. They define within them global and local library links, formatting rules, etc. -* Our required target platforms are OS X, Windows XP and Vista, and the most popular versions of Linux. All code +* Our required target platforms are OS X, Windows, and the most popular versions of Linux. All code and all products must run on all those systems. * Read the WorldWind API's Overview section for a description of WorldWind architecture, design and usage. Read the overview pages of each WorldWind package for descriptions of those. These descriptions contain critical @@ -55,14 +54,13 @@ without losing the ability to recover the default value. * Classes such as BasicDataFileStore and the logger are effectively singletons but they are not defined in their class definition as such. Their singleton nature comes from their 1:1 association with the truly singleton WorldWind class, which provides access to instances of these "singleton" classes. -* Do not use classes that are not available in the standard 1.6 JRE. Don't incur additional or external +* Do not use classes that are not available in the standard JRE. Don't incur additional or external dependencies. The only 3rd-party library we rely on is JOGL. * Constants are defined as String and namespace qualified. This enables easy and non-conflicting extension. * Do not use GUI builders to generate interfaces for examples or applications. They prevent others from being able to maintain the code. * Protect OpenGL state within a rendering unit, such as a layer, by bracketing state changes within try/finally -clauses. The util.OpenGLStackHandler utility class makes this easy. It manages both attribute state and matrix -and when it fails. +clauses. The util.OpenGLStackHandler utility class makes this easy. It manages both attribute state and matrices when it fails. * WorldWind never crashes. Always catch exceptions at least at the highest entry point from the runtime, e.g., UI listeners, thread run() methods. * Within a rendering pass WorldWind does not touch the disk or the network. Always fork off a thread to do that. @@ -72,23 +70,28 @@ usage to avoid swamping the local machine and the server. once things are set up, and the effect of something going wrong is benign. For example, Layers fork off Retriever objects to retrieve data from the network. But they don't try to keep track of these. If the retriever succeeds then the data will be available the next time the layer looks for it. The fact that it's not there -because of a timeout or something tells the layer to ask for it again if it needs it.* DOMs are expensive in memory and time. Use an event for any documents that might be large. Use the parser in +because of a timeout or something tells the layer to ask for it again if it needs it. +* DOMs are expensive in memory and time. Use an event for any documents that might be large. Use the parser in gov.nasa.worldwind.util.xml when appropriate. ### Exceptions * WW objects running in the Main thread pass exceptions through to the application unless there's good -reactive/corrective behavior that can be applied within WW.## Contributing +reactive/corrective behavior that can be applied within WW. + +## Contributing + * Log any exceptions prior to throwing them. Use the same message for the log as for the exception. * Ensure all exception messages are generated using the i18n method details below. * Public methods validate their arguments and throw the appropriate exception, typically InvalidArgumentException, and identify the exception message the parameter name and the problem -- null, out of range, etc. See the message resource file, util.MessageStrings.properties, for common messages and their identifiers. -* In Retriever threads, do not catch Throwable. Catch and react to Exception if there's a good reactive/corrective +* In Retriever threads, do not catch Throwable. Catch and react to the Exception if there's a good reactive/corrective behavior to apply, otherwise allow them to pass up the stack. Retriever threads should have an uncaught Exception handler specified for the thread. The method should log the Exception or Throwable and then return. * Private and protected methods whose calling client can't be trusted validate their arguments and throw an -appropriate exception.* The audience for exceptions is not primarily the user of the client program, but the application or WorldWind +appropriate exception. +* The audience for exceptions is not primarily the user of the client program, but the application or WorldWind developer. Throw exceptions that would let them know immediately that they're using faulty logic or data. ### Logging @@ -102,7 +105,7 @@ use any logging system other than that in the JRE. * Use level SEVERE for things that prevent the intended action,e.g., file can't be written. Use level WARN for things that don't stop the action but seem exceptional, e.g., a file was retrieved or written redundantly. Use level FINE for simple notifications. Use FINER for method traces. Using the "FINE"series prevents screen display -of these when the default JAVA logging settings are used. Since we're a component, we don't communicate such +of these when the default Java logging settings are used. Since we're a component, we don't communicate such things directly to the application's user; the application does. ### Concurrency @@ -123,7 +126,7 @@ status prior to attempting retrieval of a resource on the network. ### Documentation -* Use the appropriate Ant target to generate worldwind.jar and javadoc API documentation. Do not use the IDEA +* Use the appropriate Ant target to generate worldwind.jar and javadoc API documentation. Do not use the NetBeans Tools command because it's not configured appropriately, only the Ant targets are. * All public and protected classes, methods and fields should be commented for javadoc documentation generation. * Descriptions of classes, methods, etc. should start with a capital letter. Parameter descriptions and @@ -135,29 +138,13 @@ compared. For toString() that would be the representation returned. ### Code Formatting -* Use the code formatting and style that's in the IDEA project file. It makes it possible to review previous code +* Use the code formatting and style that's in the NetBeans project file. It makes it possible to review previous code modifications. -* Use the code formatting rules specified in WorldWindJ.ipr. They are in the project file under (Settings Project -Settings Project Code Style). To apply them, simply use Code Auto-indent Lines. You can also just check the box -at Subversion check-in time and the formatting will be applied before check-in. Be sure the formatting rules are -not overridden in your IDEA workspace. -* We generally use the traditional Sun coding conventions. Constants are in all upper case with words separated by +* We generally use the traditional Java coding conventions. Constants are in all upper case with words separated by underscores. Everything else is in camel case. Class names start with an upper case character, variables start in lower case. * White space is preferred over packing code into a small space. Please use white space liberally. -* Set up IDEA to automatically place the standard project header in newly created files by putting the following -as the File Header in the Includes tab of IDEA in the File Templates dialog:

/* Copyright (C) -2001, 2011 United States Government as represented by
the Administrator of the National Aeronautics and -Space Administration.
All Rights Reserved.
*/
package ${PACKAGE_NAME};

/**
* @author -${USER}
* @version $Id: Design and Coding Guidelines.html 1171 2013-02-11 21:45:02Z dcollins $
*/ -


Then remove the package name property from first line of the Class and Interface items of the Templates tab -in the File Templates dialog. (The package name is in the "include" now, so it gets inserted after the -copyright.) Test it out by creating a dummy class. Unfortunately this set-up is a personal configuration in -IDEA, not project specific. -* When creating a new file, the Id subversion keyword has to be explicitly set via Version Control --> Set -Property --> Property name: svn:keywords, and the term Id included in the text box. If the property is not -included in this list then Subversion doesn't replace the property string when updating the file. -* Resolve all IDEA warnings before checking in a file. If the warning refers to an intentional case, add an +* Resolve all NetBeans warnings before checking in a file. If the warning refers to an intentional case, add an exception statement. ### Internationalization (i18n) @@ -191,7 +178,6 @@ WorldWind team and community understand your report, reproduce the behavior, and #### Before Submitting a Bug Report -* Check the [**WorldWind Forum**](https://forum.worldwindcentral.com/forum/world-wind-java-forums). * Check this repository's [**issues**](https://github.com/NASAWorldWind/WorldWindJava/issues) to see if the problem has already been reported. If it has and the issue is **still open**, add a comment to the existing issue instead of opening a new one. @@ -256,7 +242,5 @@ in the appropriate repository and provide the following information: For WorldWind Java tutorials and examples, please check out our website: https://worldwind.arc.nasa.gov/. -For community support and FAQs, check out the WorldWind Forum: https://forum.worldwindcentral.com/. - -To reach our Administrative Contact, please email: [patrick.hogan@nasa.gov](mailto:patrick.hogan@nasa.gov). +To reach our Administrative Contact, please email: [Administrative Contact](mailto:worldwind-info@lists.nasa.gov) diff --git a/Design and Coding Guidelines.html b/Design and Coding Guidelines.html index 089a37e149..7322401b0a 100644 --- a/Design and Coding Guidelines.html +++ b/Design and Coding Guidelines.html @@ -1,10 +1,33 @@ - +Copyright 2006-2009, 2017, 2020 United States Government, as represented by the +Administrator of the National Aeronautics and Space Administration. +All rights reserved. + +The NASA World Wind Java (WWJ) platform is 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. + +NASA World Wind Java (WWJ) also contains the following 3rd party Open Source +software: + + Jackson Parser – Licensed under Apache 2.0 + GDAL – Licensed under MIT + JOGL – Licensed under Berkeley Software Distribution (BSD) + Gluegen – Licensed under Berkeley Software Distribution (BSD) + +A complete listing of 3rd Party software notices and licenses included in +NASA World Wind Java (WWJ) can be found in the WorldWindJava-v2.2 3rd-party +notices and licenses PDF found in code directory. + +--> +

WorldWind Multi-Platform Design and Coding Guidelines

@@ -21,7 +44,7 @@

General

them before using or modifying the code.
  • - The project's development IDE is IntelliJ IDEA. The IDEA configuration files for this project are checked in to + The project's development IDE is Apache NetBeans. The NetBeans configuration files for this project are checked in to the code repository. They define within them global and local library links, formatting rules, etc.
  • @@ -201,7 +224,7 @@

    Documentation

    Code Formatting