Repository: isis Updated Branches: refs/heads/master 421c248d7 -> 3aaad83f5
http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc index 3b2dfe2..dc62e39 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc @@ -6,17 +6,15 @@ IMPORTANT: TODO -include::_user-guide_more-advanced_bulk-actions.adoc[leveloffset=+1] +include::_user-guide_more-advanced_decoupling.adoc[leveloffset=+1] -include::_user-guide_more-advanced_triggering-events.adoc[leveloffset=+1] +include::_user-guide_more-advanced_assembling.adoc[leveloffset=+1] -include::_user-guide_more-advanced_using-modules.adoc[leveloffset=+1] +include::_user-guide_more-advanced_bulk-actions.adoc[leveloffset=+1] include::_user-guide_more-advanced_view-models.adoc[leveloffset=+1] -include::_user-guide_more-advanced_tips-n-tricks.adoc[leveloffset=+1] - -include::_user-guide_more-advanced_error-handling.adoc[leveloffset=+1] +include::_user-guide_more-advanced_transactions-and-errors.adoc[leveloffset=+1] include::_user-guide_more-advanced_i18n.adoc[leveloffset=+1] @@ -24,6 +22,10 @@ include::_user-guide_more-advanced_multi-tenancy.adoc[leveloffset=+1] include::_user-guide_more-advanced_persistence-lifecycle.adoc[leveloffset=+1] +include::_user-guide_more-advanced_neo4j.adoc[leveloffset=+1] + +include::_user-guide_more-advanced_tips-n-tricks.adoc[leveloffset=+1] + http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc new file mode 100644 index 0000000..ce73737 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc @@ -0,0 +1,63 @@ += Assembling +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. +:_basedir: ../ +:_imagesdir: images/ + +IMPORTANT: TODO + + + +== Vetoing Visibility + + + + + +== Overriding JDO Annotations + +The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations. + +For example, as of 1.9.0-SNAPSHOT the various http://www.isisaddons.org[Isis addons] modules (not ASF) use schemas for each entity. For example, the `AuditEntry` entity in the http://github.com/isisaddons/isis-module-audit[audit module] is annotated as: + +[source,java] +---- [email protected]( + identityType=IdentityType.DATASTORE, + schema = "IsisAddonsAudit", + table="AuditEntry") +public class AuditEntry { + ... +} +---- + +This will map the `AuditEntry` class to a table `"IsisAddonsAudit"."AuditEntry"`; that is using a custom schema to own the object. + +Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default. We can override the above annotation using a `package.jdo` file, for example: + +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8" ?> +<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo + http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd"; version="3.0"> + <package name="org.isisaddons.module.audit.dom"> + <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry"> + </class> + </package> +</jdo> +---- + +This file should be placed can be placed in `src/main/java/META-INF` within your application's `dom` module. + +[NOTE] +==== +* The same approach should work for any other JDO metadata, but some experimentation might be required.+ ++ +For example, in writing up the above example we found that writing `schema=""` (in an attempt to say, "use the default schema for this table") actually caused the original annotation value to be used instead. + +* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default). + +* As of 1.9.0-SNAPSHOT Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on <<_using_modules, using modules>>. +==== + http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc new file mode 100644 index 0000000..cdcaf84 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc @@ -0,0 +1,25 @@ += Decoupling +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. +:_basedir: ../ +:_imagesdir: images/ + +We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then +reason about all the classes in that package/namespace as a single unit, or module. + +This section describes how to use Isis' features to ensure that your domain application remains decoupled. The techniques described here are also the ones that have been adopted by the various http://github.com/isisaddons[Isis Addons] modules (not ASF) for security, commands, auditing etc. + +The <<_assembling, following section>> describes how to re-assemble an application, in particular where some modules are in-house but others are potentially third-party (eg the Isis Addons modules). + +[NOTE] +==== +There is some overlap with OSGi and Java 9's Jigsaw concepts of "module"; in the future we expect to refactor Isis to leverage these module systems. +==== + +include::_user-guide_more-advanced_decoupling_db-schemas.adoc[leveloffset=+1] + +include::_user-guide_more-advanced_decoupling_contributions.adoc[leveloffset=+1] + +include::_user-guide_more-advanced_decoupling_event-bus.adoc[leveloffset=+1] + + + http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc new file mode 100644 index 0000000..f91e759 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc @@ -0,0 +1,7 @@ += Contributions +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. +:_basedir: ../ +:_imagesdir: images/ + +IMPORTANT: TODO + http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc new file mode 100644 index 0000000..d341854 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc @@ -0,0 +1,152 @@ += Database Schemas +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. +:_basedir: ../ +:_imagesdir: images/ + +In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to +their own (database) schemas. As of 1.9.0-SNAPSHOT, all the http://isisaddons.org[Isis Addons] (non-ASF) modules do this, for example: + +[source,java] +---- [email protected]( ... + schema = "isissecurity", + table = "ApplicationUser") +public class ApplicationUser ... { ... } +---- + +results in a `CREATE TABLE` statement of: + +[source,sql] +---- +CREATE TABLE isissecurity."ApplicationUser" ( + ... +) +---- + + +while: + +[source,java] +---- [email protected]( ... + schema = "isisaudit", + table="AuditEntry") +public class AuditEntry ... { ... } +---- + +similarly results in: + +[source,sql] +---- +CREATE TABLE isisaudit."AuditEntry" ( + ... +) +---- + + +[TIP] +==== +If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file). See <<_overriding_jdo_annotations, Overriding Annotations>> for a write-up of how to do this. +==== + + + + +== Listener to create DB schema objects + +JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API +on the initialization of each class into the JDO metamodel. + +[TIP] +==== +Actually, the above statement isn't quite true. In DN 3.2.x (as used by Isis up to v1.8.0) there was no support for schemas. As of Isis 1.9.0-SNAPSHOT and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so for now we've decided to leave it in. +==== + +Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required. + +The guts of its implementation is: + +[source,java] +---- +package org.apache.isis.objectstore.jdo.datanucleus; + +public class CreateSchemaObjectFromClassMetadata + implements MetaDataListener, + PersistenceManagerFactoryAware, + DataNucleusPropertiesAware { + + @Override + public void loaded(final AbstractClassMetaData cmd) { ... } + + protected String buildSqlToCheck(final AbstractClassMetaData cmd) { + final String schemaName = schemaNameFor(cmd); + return String.format( + "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName); + } + + protected String buildSqlToExec(final AbstractClassMetaData cmd) { + final String schemaName = schemaNameFor(cmd); + return String.format("CREATE SCHEMA \"%s\"", schemaName); + } +} +---- + +where `MetaDataListener` is the DataNucleus listener API: + +[source,java] +---- +public interface MetaDataListener { + void loaded(AbstractClassMetaData cmd); +} +---- + +Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you +need to tweak it to support other RDBMS'. Any implementation must implement `org.datanucleus.metadata.MetaDataListener`: + +The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below). + + + +== Registering an Alternative Implementation + +An alternative implementation can be registered and used through the following configuration property: + +[source,ini] +---- +# +# hook to perform additional initialization when JDO class metadata is loaded +# default implementation will attempt to run 'create schema' for the specified schema. +# +isis.persistor.datanucleus.classMetadataLoadedListener=\ + org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata +---- +Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work. + +Any implementation must implement `org.datanucleus.metadata.MetaDataListener`. In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice. + +If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.PersistenceManagerFactoryAware`: + +[source,java] +---- +public interface PersistenceManagerFactoryAware { + public void setPersistenceManagerFactory(final PersistenceManagerFactory persistenceManagerFactory); +} +---- + +and also `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`: + +[source,java] +---- +public interface DataNucleusPropertiesAware { + public void setDataNucleusProperties(final Map<String, String> properties); +} +---- + +This latter interface provides access to the properties passed through to JDO/DataNucleus. + + +[IMPORTANT] +==== +If you do extend Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements. +==== + http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc new file mode 100644 index 0000000..5dda011 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc @@ -0,0 +1,136 @@ += Event Bus +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. +:_basedir: ../ +:_imagesdir: images/ + +IMPORTANT: TODO + +## Publishing and Subscribing to Events (Pulling Changes) + + + +## Pushing Changes + +NOTE: this technique is much less powerful than the event bus described in <<Publishing and Subscribing to Events (Pulling Changes)>>). We present it mostly for completeness. + +### When a property is changed + +If you want to invoke functionality whenever a property is changed by the user, then you should create a supporting `modifyXxx()` method and include the functionality within that. The syntax is: + +[source,java] +-- +public void modifyPropertyName(PropertyType param) { ... } +-- + +Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly. + +For example: + +[source,java] +-- +public class Order() { + public Integer getAmount() { ... } + public void setAmount(Integer amount) { ... } + public void modifyAmount(Integer amount) { // <1> + setAmount(amount); // <3> + addToTotal(amount); // <2> + } + ... +} +-- +<1> The `modifyAmount()` method calls ... +<2> ... the `addToTotal()` (not shown) to maintain some running total. + +We don't want this `addToCall()` method to be called when pulling the object back from the object store, so we put it into the modify, not the setter. + +You may optionally also specify a `clearXxx()` which works the same way as modify `modify Xxx()` but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is: + +[source,java] +-- +public void clearPropertyName() { ... } +-- + +To extend the above example: + +[source,java] +-- +public class Order() { + public Integer getAmount() { ... } + public void setAmount(Integer amount) { ... } + public void modifyAmount(Integer amount) { ... } + public void clearAmount() { + removeFromTotal(this.amount); + setAmount(null); + } + ... +} +-- + +### When a collection is added to or removed from + +A collection may have a corresponding `addToXxx()` and/or +`removeFromXxx()` method. If present, and direct manipulation of the +contents of the connection has not been disabled (see ?), then they will +be called (instead of adding/removing an object directly to the +collection returned by the accessor). + +The reason for this behaviour is to allow other behaviour to be +triggered when the contents of the collection is altered. That is, it is +directly equivalent to the supporting `modifyXxx()` and `clearXxx()` +methods for properties (see ?). + +The syntax is: + +[source,java] +-- +public void addTo<CollectionName>(EntityType param) { ... } +-- + +and + +[source,java] +-- +public void removeFromCollectionName(EntityType param) { ... } +-- + +where `EntityType` is the same type as the generic collection type. + +For example: + +[source,java] +-- +public class Employee { ... } + +public class Department { + + private int numMaleEmployees; // <1> + private int numFemaleEmployees; // <1> + + private Set<Employee> employees = new TreeSet<Employee>(); + public Set<Employee> getEmployees() { + return employees; + } + private void setEmployees(Set<Employee> employees) { + this.employees = employees; + } + public void addToEmployees(Employee employee) { + numMaleEmployees += countOneMale(employee); // <2> + numFemaleEmployees += countOneFemale(employee); // <2> + employees.add(employee); + } + public void removeFromEmployees(Employee employee) { + numMaleEmployees -= countOneMale(employee); // <3> + numFemaleEmployees -= countOneFemale(employee); // <3> + employees.remove(employee); + } + private int countOneMale(Employee employee) { return employee.isMale()?1:0; } + private int countOneFemale(Employee employee) { return employee.isFemale()?1:0; } + + ... +} +-- +<1> maintain a count of the number of male and female employees (getters and setters omitted) +<2> the `addTo...()` method increments the derived properties +<3> the `removeTo...()` method similarly decrements the derived properties + + http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_error-handling.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_error-handling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_error-handling.adoc deleted file mode 100644 index 8564571..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_error-handling.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Error Handling -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: TODO - -## Raise message/errors to users - - -## Exception Recognizers \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc new file mode 100644 index 0000000..7a8edca --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc @@ -0,0 +1,58 @@ += Neo4J +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. +:_basedir: ../ +:_imagesdir: images/ + +As of 1.8.0 Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation. + +The <<_simpleapp_archetype, SimpleApp archetype>> has been updated so that they can be optionally run under Neo4J. + +[TIP] +==== +In addition, the http://github.com/isisaddons/isis-app-neoapp}[Isis addons' neoapp] (non-ASF) is configured to run with an embedded Neo4J server running alongside the Isis webapp. +==== + +The steps below describe the configuration steps required to update an existing app. + +==== ConnectionURL + +In `persistor.properties`, update the JDO `ConnectionURL` property, eg: + +[source,ini] +---- +isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=neo4j:neo4j_DB +---- + +The other connection properties (`ConnectionDriverName`, `ConnectionUserName` and `ConnectionPassword`) should be commented out. + +==== Update pom.xml + +Add the following dependency to the `webapp` project's `pom.xml`: + +[source,xml] +---- +<dependencies> + ... + <dependency> + <groupId>org.datanucleus</groupId> + <artifactId>datanucleus-neo4j</artifactId> + <version>3.2.3</version> <!--1--> + </dependency> + ... +</dependencies> +---- +<1> for 1.8.0, use the value shown. for 1.9.0-SNAPSHOT, use 4.0.5. + +In the <<_simpleapp_archetype, SimpleApp archetype>> this is defined under the "neo4j" profile so can be activated using `-P neo4j`. + +==== Try it out! + +If you want to quickly try out neo4j for yourself: + +* run the <<_simpleapp_archetype, SimpleApp archetype>> (v1.8.0) + +* build the app: + +* run the app: + +If you visit the about page you should see the neo4j JAR files are linked in, and a `neo4j_DB` subdirectory within the `webapp` directory. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc index 6fb0262..c555440 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc @@ -8,8 +8,6 @@ IMPORTANT: TODO include::_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc[leveloffset=+1] -include::_user-guide_more-advanced_tips-n-tricks_overriding-jdo-annotations.adoc[leveloffset=+1] - include::_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc[leveloffset=+1] include::_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_overriding-jdo-annotations.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_overriding-jdo-annotations.adoc deleted file mode 100644 index c528103..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_overriding-jdo-annotations.adoc +++ /dev/null @@ -1,6 +0,0 @@ -= Overriding JDO Annotations -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: TODO \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc new file mode 100644 index 0000000..d666d0a --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc @@ -0,0 +1,26 @@ += Transactions and Errors +:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. +:_basedir: ../ +:_imagesdir: images/ + +In Isis, every action invocation (in fact, every interaction) is automatically wrapped in a transaction, and any repository query automatically does a flush. + +What that means is that there's no need to explicitly start or commit transactions in Isis; this will be done for you. Indeed, if you do try to manage transactions (eg by reaching into the JDO `PersistenceManager` exposed by the <<_isis_jdo_support, IsisJdoSupport>> domain service, then you are likely to confuse Isis and get a stack trace for your trouble. + +== Aborting Transactions + +If you want to abort Isis' transaction, this can be done by throwing `RecoverableException` (or any subclass, eg `ApplicationException`). The transaction will be aborted, and the exception message will be displayed to the user. + +If you throw any other exception (ie not a subclass of `RecoverableException`), then the users will see an error page (if Wicket viewer) or a 500 (if Restful Objects viewer). + + +== Raise message/errors to users + +IMPORTANT: TODO + + + +== Exception Recognizers + +IMPORTANT: TODO + http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_triggering-events.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_triggering-events.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_triggering-events.adoc deleted file mode 100644 index 67c6552..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_triggering-events.adoc +++ /dev/null @@ -1,136 +0,0 @@ -= Triggering Events -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: TODO - -## Publishing and Subscribing to Events (Pulling Changes) - - - -## Pushing Changes - -NOTE: this technique is much less powerful than the event bus described in <<Publishing and Subscribing to Events (Pulling Changes)>>). We present it mostly for completeness. - -### When a property is changed - -If you want to invoke functionality whenever a property is changed by the user, then you should create a supporting `modifyXxx()` method and include the functionality within that. The syntax is: - -[source,java] --- -public void modifyPropertyName(PropertyType param) { ... } --- - -Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly. - -For example: - -[source,java] --- -public class Order() { - public Integer getAmount() { ... } - public void setAmount(Integer amount) { ... } - public void modifyAmount(Integer amount) { // <1> - setAmount(amount); // <3> - addToTotal(amount); // <2> - } - ... -} --- -<1> The `modifyAmount()` method calls ... -<2> ... the `addToTotal()` (not shown) to maintain some running total. - -We don't want this `addToCall()` method to be called when pulling the object back from the object store, so we put it into the modify, not the setter. - -You may optionally also specify a `clearXxx()` which works the same way as modify `modify Xxx()` but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is: - -[source,java] --- -public void clearPropertyName() { ... } --- - -To extend the above example: - -[source,java] --- -public class Order() { - public Integer getAmount() { ... } - public void setAmount(Integer amount) { ... } - public void modifyAmount(Integer amount) { ... } - public void clearAmount() { - removeFromTotal(this.amount); - setAmount(null); - } - ... -} --- - -### When a collection is added to or removed from - -A collection may have a corresponding `addToXxx()` and/or -`removeFromXxx()` method. If present, and direct manipulation of the -contents of the connection has not been disabled (see ?), then they will -be called (instead of adding/removing an object directly to the -collection returned by the accessor). - -The reason for this behaviour is to allow other behaviour to be -triggered when the contents of the collection is altered. That is, it is -directly equivalent to the supporting `modifyXxx()` and `clearXxx()` -methods for properties (see ?). - -The syntax is: - -[source,java] --- -public void addTo<CollectionName>(EntityType param) { ... } --- - -and - -[source,java] --- -public void removeFromCollectionName(EntityType param) { ... } --- - -where `EntityType` is the same type as the generic collection type. - -For example: - -[source,java] --- -public class Employee { ... } - -public class Department { - - private int numMaleEmployees; // <1> - private int numFemaleEmployees; // <1> - - private Set<Employee> employees = new TreeSet<Employee>(); - public Set<Employee> getEmployees() { - return employees; - } - private void setEmployees(Set<Employee> employees) { - this.employees = employees; - } - public void addToEmployees(Employee employee) { - numMaleEmployees += countOneMale(employee); // <2> - numFemaleEmployees += countOneFemale(employee); // <2> - employees.add(employee); - } - public void removeFromEmployees(Employee employee) { - numMaleEmployees -= countOneMale(employee); // <3> - numFemaleEmployees -= countOneFemale(employee); // <3> - employees.remove(employee); - } - private int countOneMale(Employee employee) { return employee.isMale()?1:0; } - private int countOneFemale(Employee employee) { return employee.isFemale()?1:0; } - - ... -} --- -<1> maintain a count of the number of male and female employees (getters and setters omitted) -<2> the `addTo...()` method increments the derived properties -<3> the `removeTo...()` method similarly decrements the derived properties - - http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_using-modules.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_using-modules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_using-modules.adoc deleted file mode 100644 index 8872a55..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_using-modules.adoc +++ /dev/null @@ -1,154 +0,0 @@ -= Using Modules -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -NOTE: 1.9.0-SNAPSHOT onwards. - -We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then -reason about all the classes in that package/namespace as a single unit. Good examples are the various -http://github.com/isisaddons[Isis Addons] (not ASF): security, commands, auditing and so on. - -In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to -their own (database) schemas. As of 1.9.0-SNAPSHOT, all the IsisAddons modules do this, for example: - -[source,java] ----- [email protected]( ... - schema = "isissecurity", - table = "ApplicationUser") -public class ApplicationUser ... { ... } ----- - -results in a `CREATE TABLE` statement of: - -[source,sql] ----- -CREATE TABLE isissecurity."ApplicationUser" ( - ... -) ----- - - -while: - -[source,java] ----- [email protected]( ... - schema = "isisaudit", - table="AuditEntry") -public class AuditEntry ... { ... } ----- - -similarly results in: - -[source,sql] ----- -CREATE TABLE isisaudit."AuditEntry" ( - ... -) ----- - - -If for some reason you don't want to use schemas (though we strongly recommend that you do), then then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file). See <<Overriding Annotations>> for a write-up of how to do this. - - - -== Listener to create DB schema objects - -JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API -on the initialization of each class into the JDO metamodel. - -[TIP] -==== -Actually, the above statement isn't quite true. In DN 3.2.x (as used by Isis up to v1.8.0) there was no support for schemas. As of Isis 1.9.0-SNAPSHOT and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so we've decided to leave it in. -==== - -Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required. - -The guts of its implementation is: - -[source,java] ----- -package org.apache.isis.objectstore.jdo.datanucleus; - -public class CreateSchemaObjectFromClassMetadata - implements MetaDataListener, - PersistenceManagerFactoryAware, - DataNucleusPropertiesAware { - - @Override - public void loaded(final AbstractClassMetaData cmd) { ... } - - protected String buildSqlToCheck(final AbstractClassMetaData cmd) { - final String schemaName = schemaNameFor(cmd); - return String.format( - "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName); - } - - protected String buildSqlToExec(final AbstractClassMetaData cmd) { - final String schemaName = schemaNameFor(cmd); - return String.format("CREATE SCHEMA \"%s\"", schemaName); - } -} ----- - -where `MetaDataListener` is the DataNucleus listener API: - -[source,java] ----- -public interface MetaDataListener { - void loaded(AbstractClassMetaData cmd); -} ----- - -Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you -need to tweak it to support other RDBMS'. Any implementation must implement `org.datanucleus.metadata.MetaDataListener`: - -The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below). - - - -== Registering an Alternative Implementation - -An alternative implementation can be registered and used through the following configuration property: - -[source,ini] ----- -# -# hook to perform additional initialization when JDO class metadata is loaded -# default implementation will attempt to run 'create schema' for the specified schema. -# -isis.persistor.datanucleus.classMetadataLoadedListener=\ - org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata ----- -Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work. - -Any implementation must implement `org.datanucleus.metadata.MetaDataListener`. In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice. - -If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.PersistenceManagerFactoryAware`: - -[source,java] ----- -public interface PersistenceManagerFactoryAware { - public void setPersistenceManagerFactory(final PersistenceManagerFactory persistenceManagerFactory); -} ----- - -and also `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`: - -[source,java] ----- -public interface DataNucleusPropertiesAware { - public void setDataNucleusProperties(final Map<String, String> properties); -} ----- - -This latter interface provides access to the properties passed through to JDO/DataNucleus. - - - - -== Please contribute back - -If you do extend Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements. http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc index 84b2dd1..8a7ebf2 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc @@ -9,8 +9,6 @@ include::_user-guide_reference_recognized-methods.adoc[leveloffset=+1] include::_user-guide_reference_annotations.adoc[leveloffset=+1] -include::_user-guide_reference_configuration-properties.adoc[leveloffset=+1] - include::_user-guide_reference_domain-services.adoc[leveloffset=+1] include::_user-guide_reference_value-types.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc deleted file mode 100644 index 68788ed..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Configuration Properties -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: WIP... - -This section lists the configuration properties recognized by Apache Isis. - -include::_user-guide_reference_configuration-properties_core.adoc[leveloffset=+1] - -include::_user-guide_reference_configuration-properties_wicket-viewer.adoc[leveloffset=+1] - -include::_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc[leveloffset=+1] - -include::_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc[leveloffset=+1] - http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc deleted file mode 100644 index ff525c0..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc +++ /dev/null @@ -1,41 +0,0 @@ -= Core -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: WIP... - -.Core Configuration Properties -[cols="2a,1,3a", options="header"] -|=== -|Property -|Value + -(_default value_) -|Description - -|`isis.services` -|`FQCN`,`FQCN2`,... -|Fully qualified class names of classes to be instantiated as domain services. Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to `@DomainServiceLayout#menuOrder()`). - -|`isis.services.` + -`container.disableAutoFlush` -|`true`,`_false_` -|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on). - -|`isis.persistor.` + -`disableConcurrencyChecking` -|`true`,`_false_` -| Disables concurrency checking globally. Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself. (Note that there is no "datanucleus" in the property). - -|`isis.reflector.facet.` + -`cssClassFa.patterns` -|regex:fa-icon,regex2:fa-icon2,... -|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. - -|`isis.reflector.facet.` + -`cssClass.patterns` -|regex:css1,regex2:css2,... -|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. - -|=== - http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc deleted file mode 100644 index 5b4e951..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= JDO/Datanucleus Objectstore -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: WIP... - -These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together). - -== Configuration Properties for Apache Isis itself - - -.JDO/DataNucleus Objectstore Configuration Properties -[cols="2a,1,3a", options="header"] -|=== -|Property -|Value + -(_default value_) -|Description - -|`isis.persistor.datanucleus.` + -`RegisterEntities.packagePrefix` -| fully qualified package names (CSV) -| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used). -Further <<_registering_entity_types, discussion below>>. - -|`isis.persistor.datanucleus.` + -`PublishingService.serializedForm` -| zipped -| - -|=== - -== Configuration Properties passed through directly to DataNucleus. - -.JDO/DataNucleus Objectstore Configuration Properties -[cols="2a,1,3a", options="header"] -|=== -|Property -|Value + -(_default value_) -|Description - -|`isis.persistor.datanucleus.impl.*` -| -| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped) - -|`isis.persistor.datanucleus.impl.` + -`datanucleus.persistenceByReachabilityAtCommit` -|`false` -|We recommend this setting is disabled. + -Further <<_disabling_persistence_by_reachability, discussion below>>. - -|=== - -include::_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc[leveloffset=+1] - -include::_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc deleted file mode 100644 index 5c0b109..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc +++ /dev/null @@ -1,93 +0,0 @@ -= Disabling Persistence by Reachability -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -By default, JDO/DataNucleus supports the concept of http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html[persistence-by-reachability]. That is, if -a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods. - -However, convenient though this feature is, you may find that it causes performance issues. - -[WARNING] -==== -DataNucleus' persistence-by-reachability may cause performance issues. We strongly recommend that you disable it. -==== - -One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Isis' link:../../../reference/Utility.html[ObjectContracts] utility. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below). - -We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`: - -[source,ini] ----- -isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false ----- - -This change has been made to the <<_simpleapp_archetype, SimpleApp Archetype>> - -If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods. - -== Explanation of the issue in more detail - -Consider the entities: - -image::{_imagesdir}reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png[width="750px"] - - -[TIP] -==== -[source] -.DSL (http://yuml.me/edit/b8681268[yuml.me/b8681268]) ----- -[Party|reference]<--->*[AgreementRole|startDate] -[AgreementRole]*<-->[Agreement|reference] ----- -==== - - -In the course of a transaction, the `Agreement` entity is loaded into memory (not necessarily modified), and then new ``AgreementRole``s are associated to it. - -All these entities implement `Comparable` using `ObjectContracts`, and the implementation of ``AgreementRole``'s (simplified) is: - -[source,java] ----- -public class AgreementRole { - ... - public int compareTo(AgreementRole other) { - return ObjectContracts.compareTo(this, other, "agreement","startDate","party"); - } -} ----- - -while ``Agreement``'s is implemented as: - -[source,java] ----- -public class Agreement { - ... - public int compareTo(Agreement other) { - return ObjectContracts.compareTo(this, other, "reference"); - } -} ----- - -and ``Party``'s is similarly implemented as: - -[source,java] ----- -public class Party { - ... - public int compareTo(Party other) { - return ObjectContracts.compareTo(this, other, "reference"); - } -} ----- - -DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire: - -* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries - -* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory - -* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance. - -In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc deleted file mode 100644 index 3748ac3..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= Eagerly Registering Entity Types -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -[WARNING] -==== -From 1.6.0+ this feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847]. -==== - -Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Isis builds its metamodel by walking the graph of types from the services registered using `@DomainService` or explicitly registered in `isis.properties`. The JDO objectstore then takes these types and registers them with DataNucleus. - -In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered. - -Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating). - -In any case, it's probably not good practice to have DataNucleus work this way. The `RegisterEntities` service can therefore be registered in order to do the eager registration. It searches for all `@PersistenceCapable` entities under specified package(s), and registers them all. - - -== Specify the Package Prefix(es) - -In the `persistor_datanucleus.properties`, specify the package prefix(es) of your application, to provide a hint for finding the `@PersistenceCapable` classes. - -The value of this property can be a comma-separated list (if there is more than one package or Maven module that holds persistable entities). - - -== Integration Testing - -The `IsisConfigurationForJdoIntegTests`, recommended for use in <<_integration_testing, Integration Testing>> provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property: - -[source,java] -.Integration test bootstrapping ----- -private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder { - ... - private static IsisConfiguration testConfiguration() { - final IsisConfigurationForJdoIntegTests testConfiguration = new IsisConfigurationForJdoIntegTests(); - testConfiguration.addRegisterEntitiesPackagePrefix("domainapp.dom.modules"); // <1> - return testConfiguration; - } -} ----- -<1> specify the package prefix(es) for integration testing. http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc deleted file mode 100644 index a932663..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc +++ /dev/null @@ -1,21 +0,0 @@ -= RestfulObjects Viewer -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: WIP... - -These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together). - - -.RestfulObjects Viewer Configuration Properties -[cols="2a,1,3", options="header"] -|=== -|Property -|Value + -(_default value_) -|Description - -|=== - - http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc deleted file mode 100644 index e613d3a..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= Wicket Viewer -:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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. -:_basedir: ../ -:_imagesdir: images/ - -IMPORTANT: WIP... - -These configuration properties are typically stored in `WEB-INF/viewer_wicket.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together). - - -.Wicket Viewer Configuration Properties -[cols="2a,1,3", options="header"] -|=== -|Property -|Value + -(_default value_) -|Description - -|`isis.viewer.wicket.` + -`suppressRememberMe` -|`true`,`_false_` -| - -|`isis.viewer.wicket.` + -`disableModalDialogs` -|`true`,`_false_` -| - -|`isis.viewer.wicket.` + -`stripWicketTags` -|`true`,`false` -| Whether to force Wicket tags to be stripped. + -The default is for them to be stripped in production (Isis' SERVER mode == Wicket DEPLOYMENT mode), but not stripped otherwise (Isis' PROTOTYPE mode == Wicket DEVELOPMENT mode) - -|`isis.viewer.wicket.` + -`bookmarkedPages` -| +ve int (`_15_`) -| number of pages to bookmark - - -|`isis.viewer.wicket.` + -`regularCase` -| `true`,`_false_` -| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI - -|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection` -| `true`,`_false_` -| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes. - -|=== - - http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png new file mode 100644 index 0000000..0496a84 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png new file mode 100644 index 0000000..42d7480 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png new file mode 100644 index 0000000..9c4c480 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png new file mode 100644 index 0000000..91d1a61 Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png new file mode 100644 index 0000000..7ff133c Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png differ http://git-wip-us.apache.org/repos/asf/isis/blob/3aaad83f/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc index deb64a6..e252a27 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc @@ -14,8 +14,6 @@ include::_user-guide_more-advanced.adoc[leveloffset=+1] include::_user-guide_reference.adoc[leveloffset=+1] -include::_user-guide_decoupling.adoc[leveloffset=+1] - include::_user-guide_testing.adoc[leveloffset=+1] include::_user-guide_wicket-viewer.adoc[leveloffset=+1]
