Parameter --------- The connection parameters are described using the ``Parameter`` class. There is also a small extension to this idea with the ``DataAccessFactory.Param`` class. The extension provided for backwards compatibility, as the methods focus on data entry and has been superseded by the Converters class. .. image:: /images/param.PNG The ``Parameter`` is used for: * ``DataAccessFactory.getParameterInfo()`` To describe the keys and values to put into your map. You can use this information to ask your end users the details about their data such as if they want an index created for their shapefile access. * ``ProcessFactory`` in ``gt-process`` to describe the parameters to geospatial processes. * ``JDataStoreWizard`` from ``gt-swing`` used to allow users to connect to data in our tutorials. In all these cases the Parameter are used to describe the contents of a ``Map``. The class itself is open ended, with only a few well defined restrictions advertised at this time. The following public fields are available: * ``Parameter.key`` : ``String`` Programmatic machine readable key or name used to store the value. Suitable for use in a ``java.util.Map`` of connection parameters. * ``Parameter.type`` : ``Class`` Formal restriction on the type of the Java Object allowed as a value. May be used in conjunction with ``minOccurs`` and ``maxOccurs`` when a ``List`` of values is allowed. * ``Parameter.title`` : ``InternationalString`` * ``Parameter.description`` : ``InternationalString`` Human readable title and description for data entry prompting. * ``Parameter.required`` : ``boolean`` * ``Parameter.minOccurs`` : ``int`` * ``Parameter.maxOccurs`` : ``int`` Indication of if the value is required, or if more than one value is allowed and any restrictions on the resulting list. * ``Parameter.sample`` : ``Object`` A sample, or default, value that can be shown to users as a starting point. * ``Parameter.metadata`` : ``Map`` Here is where the ``Parameter`` description becomes open ended, as you can add your own restrictions and information to this "metadata" map. We have defined a series of well known keys (with javadocs): * ``FEATURE_TYPE`` - when the ``Parameter.type`` is a ``SimpleFeature``, this key is used to record the expected ``FeatureType`` * ``IS_PASSWORD`` Example use:: // Using IS_PASSWORD to check Parameter.metadata field.setPassword( Boolean.TRUE.equals( parameter.metadata.get( Parameter.IS_PASSWORD ))); // Or use the utility method field.setPassword( parameter.isPassword() ); * ``LENGTH`` Example use:: Integer length = parameter.metadata.get( Parameter.LENGTH ); field.setLength( length == null ? 40 : length ); * ``CRS`` - when the parameter type is spatial (such as a ``Geometry`` or ``Feature``) this records the expected ``CoordinateReferenceSystem`` * ``ELEMENT`` - used to indicate the element type for a ``List`` * ``MIN`` - minimum value for any comparable such as a ``Number``, ``Date`` or ``String``. Assumed to be the same ``Class`` as ``Parameter.type``. * ``MAX`` - maximum value for any comparable such as a ``Number``, ``Date`` or ``String``. Assumed to be the same ``Class`` as ``Parameter.type``. * ``EXT`` - extension used for selecting Files * ``LEVEL`` - indicates if the parameter is suitable for a general "user", "advanced" user, or only applicable to a "program" (such as a JEE Session). A number of constructors are available. It is recommended that you use ``KVP`` when defining the metadata map (as it was created with this express purpose in mind). A couple of methods have been defined; to solidify how the metadata map above is used: * ``Parameter.isPassword()`` - check if ``metadata.get(IS_PASSWORD)`` is true * ``Parameter.getLevel()`` - check if level is "user", "advanced" or "program" (defaulting to "user"). The ``Param`` subclass only offers a few additional ideas: * ``Param.lookUp(Map)`` Used to safely look up a value in a map of connection parameters:: // Server is required; so if is not available an IOException is thrown String server = (String) SERVER.lookup( connectionParameters ); // May be null as PORT is optional // Is able to type convert a String to an Integer to match PORT.type Integer port = (Integer) PORT.lookup( connectionParams ); if( port == null ){ port = PORT.sample; // default port for PostGIS } * ``Param.text(Object)`` Convert object to an appropriate ``String`` representation for display to a user. * ``Param.parse(String)`` Used to parse a user supplied String into the required Class indicated by ``Param.type``. * ``Param.handle(String)`` Convert a ``String`` to the required ``Class``; with the extra ability to handle arrays of values:: Param DASH = new Param( "dash", int[].class ); int[] arrary = (int[]) DASH.handle("1 2 3 4 5 6"); Convert a ``String`` (provide by the user) to the required ``Class`` indicated by ``Param.type``, handling arrays using white space if required.