ISIS-1133: more adocs.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/3cd72ab9 Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/3cd72ab9 Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/3cd72ab9 Branch: refs/heads/master Commit: 3cd72ab9c0a8702b4861706eddfbae00daabf70c Parents: 5c8fb46 Author: Dan Haywood <[email protected]> Authored: Wed May 6 18:26:17 2015 +0100 Committer: Dan Haywood <[email protected]> Committed: Wed May 6 18:26:17 2015 +0100 ---------------------------------------------------------------------- .../_/customizing-the-welcome-page.adoc | 33 ++ .../user-guide/_user-guide_configuration.adoc | 29 -- ...e_configuration_configuring-datanucleus.adoc | 20 - ...s_disabling-persistence-by-reachability.adoc | 93 ---- ...atanucleus_eagerly-registering-entities.adoc | 43 -- ...configuring-datanucleus_persistence-xml.adoc | 9 - ...ring-datanucleus_using-jndi-data-source.adoc | 72 ---- ...r-guide_configuration_configuring-shiro.adoc | 419 ------------------ .../_user-guide_configuration_files.adoc | 87 ---- ...r-guide_configuration_integration-tests.adoc | 13 - .../_user-guide_configuration_properties.adoc | 15 - ...ser-guide_configuration_properties_core.adoc | 41 -- ...tion_properties_datanucleus-objectstore.adoc | 57 --- ...ration_properties_restfulobjects-viewer.adoc | 21 - ..._configuration_properties_wicket-viewer.adoc | 52 --- .../_user-guide_configuration_web-xml.adoc | 19 - .../user-guide/_user-guide_deployment.adoc | 4 + .../_user-guide_deployment_cmd-line.adoc | 29 ++ .../_user-guide_deployment_jvm-flags.adoc | 18 + ..._user-guide_extending_programming-model.adoc | 8 +- .../_user-guide_extending_wicket-viewer.adoc | 237 ++++++++++- .../user-guide/_user-guide_reference.adoc | 4 - .../_user-guide_reference_cmd-line-args.adoc | 31 -- .../_user-guide_reference_web-xml.adoc | 8 - .../_user-guide_restful-objects-viewer.adoc | 230 ---------- .../_user-guide_restfulobjects-viewer.adoc | 24 ++ ...objects-viewer_configuration_properties.adoc | 181 ++++++++ ...er-guide_restfulobjects-viewer_features.adoc | 22 + ...de_restfulobjects-viewer_hints-and-tips.adoc | 75 ++++ .../_user-guide_runtime-configuration.adoc | 34 ++ ...e-configuration_configuring-datanucleus.adoc | 20 + ...s_disabling-persistence-by-reachability.adoc | 93 ++++ ...atanucleus_eagerly-registering-entities.adoc | 43 ++ ...configuring-datanucleus_persistence-xml.adoc | 9 + ...ring-datanucleus_using-jndi-data-source.adoc | 72 ++++ ...runtime-configuration_configuring-shiro.adoc | 419 ++++++++++++++++++ ..._user-guide_runtime-configuration_files.adoc | 87 ++++ ...runtime-configuration_integration-tests.adoc | 13 + ...-guide_runtime-configuration_properties.adoc | 12 + ...e_runtime-configuration_properties_core.adoc | 41 ++ ...tion_properties_datanucleus-objectstore.adoc | 57 +++ ...ser-guide_runtime-configuration_web-xml.adoc | 19 + .../user-guide/_user-guide_wicket-viewer.adoc | 426 +------------------ ...e_wicket-viewer_application-menu-layout.adoc | 170 ++++++++ ..._wicket-viewer_configuration_properties.adoc | 90 ++++ ..._user-guide_wicket-viewer_customisation.adoc | 247 +++++++++++ .../_user-guide_wicket-viewer_features.adoc | 131 ++++++ .../_user-guide_wicket-viewer_isis-addons.adoc | 32 ++ .../wicket-viewer/about-page/about-page.png | Bin 0 -> 59612 bytes .../wicket-viewer/application-menu/tertiary.png | Bin 0 -> 11491 bytes .../main/asciidoc/user-guide/user-guide.adoc | 12 +- adocs/template/document.html.erb | 1 + 52 files changed, 2229 insertions(+), 1693 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc new file mode 100644 index 0000000..9c1688a --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_/customizing-the-welcome-page.adoc @@ -0,0 +1,33 @@ +Title: Customizing the Welcome Page + +It's possible to customize the application name, welcome message and about message can also be customized. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`: + +[source] +---- +public class MyAppApplication extends IsisWicketApplication { + @Override + protected Module newIsisWicketModule() { + final Module isisDefaults = super.newIsisWicketModule(); + final Module myAppOverrides = new AbstractModule() { + @Override + protected void configure() { + ... + bind(String.class) + .annotatedWith(Names.named("applicationName")) + .toInstance("My Wonderful App"); + bind(String.class) + .annotatedWith(Names.named("welcomeMessage")) + .toInstance(readLines("welcome.html")); + bind(String.class) + .annotatedWith(Names.named("aboutMessage")) + .toInstance("My Wonderful App v1.0"); + ... + } + }; + + return Modules.override(isisDefaults).with(myAppOverrides); + } +} +---- + +Here the `welcome.html` file is resolved relative to `src/main/webapp`. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration.adoc deleted file mode 100644 index 84bca3b..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration.adoc +++ /dev/null @@ -1,29 +0,0 @@ -= Configuration -: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/ - - -Isis' own configuration properties are simple key-value pairs, typically held in the `WEBINF/isis.properties` file and other related files. This chapter describes how to configure an Apache Isis application. - -[TIP] -==== -The configuration values are "baked" into the WAR file. Details on how to override these configuration properties externally for different environments can be found in the <<_deployment,Deployment>> chapter. -==== - -include::_user-guide_configuration_files.adoc[leveloffset=+1] - -include::_user-guide_configuration_properties.adoc[leveloffset=+1] - -include::_user-guide_configuration_web-xml.adoc[leveloffset=+1] - -include::_user-guide_configuration_configuring-shiro.adoc[leveloffset=+1] - -include::_user-guide_configuration_configuring-datanucleus.adoc[leveloffset=+1] - -include::_user-guide_configuration_integration-tests.adoc[leveloffset=+1] - - - - - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus.adoc deleted file mode 100644 index 9794c76..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus.adoc +++ /dev/null @@ -1,20 +0,0 @@ -= Configuring DataNucleus -: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/ - -Apache Isis programmatically configures DataNucleus; any Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course). - -DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit". n theory it could also hold mappings, though in Isis we tend to use annotations instead. - -Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`. A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here]. The metadata in these XML can be used to override the annotations of annotated entities; see <<_overriding_jdo_annotations, Overriding JDO Annotatons>> for further discussion. - - - -include::_user-guide_configuration_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1] - -include::_user-guide_configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1] - -include::_user-guide_configuration_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1] - -include::_user-guide_configuration_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_disabling-persistence-by-reachability.adoc deleted file mode 100644 index 5c0b109..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_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/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_eagerly-registering-entities.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_eagerly-registering-entities.adoc deleted file mode 100644 index 3748ac3..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_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/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_persistence-xml.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_persistence-xml.adoc deleted file mode 100644 index 7933b17..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_persistence-xml.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= `persistence.xml` -: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/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_using-jndi-data-source.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_using-jndi-data-source.adoc deleted file mode 100644 index 9888750..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-datanucleus_using-jndi-data-source.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= Using JNDI DataSource -: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/ - -Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource. - - - -== Application managed connections - -Using a connection pool managed directly by the application (that is, by Isis' JDO objectstore and ultimately by DataNucleus) requires a single set of configuration properties to be specified. - -In the `WEB-INF\persistor_datanucleus.properties` file, specify the connection driver, url, username and password. - -For example: - -[source,ini] ----- -isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy -isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test -isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa -isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword= ----- - -Those configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed). - - - -== Container managed (JNDI) datasource - -Using a datasource managed by the servlet container requires three separate bits of configuration. - -Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example: - -If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed). - -Secondly, in the `WEB-INF/web.xml`, declare the resource reference: - -[source,xml] ----- -<resource-ref> - <description>db</description> - <res-ref-name>jdbc/simpleapp</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> -</resource-ref> ----- - -Finally, declare the datasource as required by the servlet container. For example, if using Tomcat 7, the datasource can be specified by adding the following to `$TOMCAT_HOME/conf/context.xml`: - -[source,xml] ----- -<Resource name="jdbc/simpleapp" - auth="Container" - type="javax.sql.DataSource" - maxActive="100" - maxIdle="30" - maxWait="10000" - username="sa" - password="p4ssword" - driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" - url="jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp"/> ----- - -You will also need to make sure that the JDBC driver is on the servlet container's classpath. For Tomcat, this means copying the driver to `$TOMCAT_HOME/lib`. - -[NOTE] -==== -According to Tomcat's documentation, it is supposedly possible to copy the `conf/context.xml` to the name of the webapp, eg `conf/mywebapp.xml`, and scope the connection to that webapp only. I was unable to get this working, however. -==== - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc deleted file mode 100644 index 7907707..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_configuring-shiro.adoc +++ /dev/null @@ -1,419 +0,0 @@ -= Configuring Shiro -: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/ - - -Apache Isis' security mechanism is configurable, specifying an `Authenticator` and an `Authorizor` (non-public) APIs. The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces. - -[TIP] -==== -The <<_simpleapp_archetype, SimpleApp archetype>> is pre-configured to use Apache Shiro, so much of what follows is set up already. -==== - -== Specifying Shiro as the security mechanism - -To tell Apache Isis to use Shiro, update the `WEB-INF/isis.properties` file: - -[source,ini] ----- -isis.authentication=shiro -isis.authorization=shiro ----- - -This installs the appropriate implementation (the `ShiroAuthenticatorOrAuthorizor` class) that use Shiro's APIs to perform authentication and authorization. - - - - -== Bootstrapping Shiro - -The Shiro environment (in essence, thread-locals holding the security credentials) needs to be bootstrapped using the following settings in the `WEB-INF/web.xml` file: - -[source,xml] ----- -<listener> - <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class> -</listener> - -<filter> - <filter-name>ShiroFilter</filter-name> - <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class> -</filter> - -<filter-mapping> - <filter-name>ShiroFilter</filter-name> - <url-pattern>/*</url-pattern> -</filter-mapping> ----- - -Based on this Shiro will then read `WEB-INF/shiro.ini` file to configure its Realm definitions for authentication and authorization. - - - - -== `WEB-INF/shiro.ini` - -The `shiro.ini` file (at least as configured in the <<_simpleapp_archetype, SimpleApp archetype>>) is configured to use the built-in `$iniRealm`. This is achieved by the line: - -[source,ini] ----- -securityManager.realms = $iniRealm ----- - -The file also (by way of example) include entries to setup an ldapRealm, but this is not wired in. For more information on LDAP, see link:./using-ldap.html[here]. - -Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself. - -* the users/passwords and their roles from the `[users]` sections; -* the roles are mapped to permissions in the `[roles]` section. - - -=== Users section - -The `[users]` section lists users, passwords and their roles. For example: - -[source,ini] ----- -sven = pass, admin_role -dick = pass, user_role, analysis_role, self-install_role -bob = pass, user_role, self-install_role ----- - -=== Roles section - -The `roles` section lists roles and their corresponding permissions. For example: - -[source,ini] ----- -user_role = *:ToDoItems:*:*,\ - *:ToDoItem:*:*,\ - *:ToDoAppDashboard:*:* -analysis_role = *:ToDoItemAnalysis:*:*,\ - *:ToDoItemsByCategoryViewModel:*:*,\ - *:ToDoItemsByDateRangeViewModel:*:* -self-install_role = *:ToDoItemsFixturesService:install:* -admin_role = * ----- - -=== Permissions format - -The permission format is configurable. The default format is: - -[source,ini] ----- -packageName:className:memberName:r,w ----- - -where: - -* `memberName` is the property, collection or action name. -* `r` indicates that the member is visible -* `w` indicates that the member is usable (editable or invokable) - -and where each of the parts of the permission string can be wildcarded using `*`. - -Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards. Thus: - -[source] ----- -com.mycompany.myapp:Customer:firstName:r,w # view or edit customer's firstName -com.mycompany.myapp:Customer:lastName:r # view customer's lastName only -com.mycompany.myapp:Customer:placeOrder:* # view and invoke placeOrder action -com.mycompany.myapp:Customer:placeOrder # ditto -com.mycompany.myapp:Customer:*:r # view all customer class members -com.mycompany.myapp:*:*:r # view-only access for all classes in myapp package -com.mycompany.myapp:*:*:* # view/edit for all classes in myapp package -com.mycompany.myapp:*:* # ditto -com.mycompany.myapp:* # ditto -com.mycompany.myapp # ditto -* # view/edit access to everything ----- - - - - -==== Using the Enhanced Isis Permission Syntax - -Shiro also allows the conversion to be mapped to alternative `Permission` instances; Isis provides its own `IsisPermission` which provides an extended and more flexible syntax. - - -Isis defines its own extended syntax for permissions, following the format: - -[source,ini] ----- -([!]?)([^/]+)[/](.+) ----- - -where: - -* the optional `!` prefix indicates this permission is a vetoing permission -* the optional `xxx/` prefix is a permission group that scopes any vetoing permissions -* the remainder of the string is the permission (possibly wildcarded, with :rw as optional suffix) - -For example: - -[source,ini] ----- -user_role = !reg/org.estatio.api,\ - !reg/org.estatio.webapp.services.admin,\ - reg/* ; \ -api_role = org.estatio.api ;\ -admin_role = adm/* ----- - -sets up: -* the user role with access to all permissions except those in `org.estatio.api` and `org.estatio.webapp.services.admin` -* the api_role with access to all permissions in `org.estatio.api` -* the admin_role with access to everything. - -The permission group concept is required to scope the applicability of any veto permission. This is probably best explained by an example. Suppose that a user has both `admin_role` and `user_role`; we would want the `admin_role` to trump the vetos of the `user_role`, in other words to give the user access to everything. Because of the permission groups, the two `!reg/...` vetos in user_role only veto out selected permissions granted by the `reg/*` permissions, but they do not veto the permissions granted by a different scope, namely `adm/*`. The net effect is what we would want: that a user with both `admin_role` and `user_role` would have access to everything, irrespective of those two veto permissions of the `user_role`. - -To tell Shiro to use the Isis permission format, add the following to `shiro.ini`: - -[source,ini] ----- -permissionResolver = org.apache.isis.security.shiro.authorization.IsisPermissionResolver -xxxRealm.permissionResolver = $permissionResolver ----- - -where `xxxRealm` is the realm to be configured. - - - -== Multiple Realms - -A more sophisticated approach is to use external realms. For example, to configure two text-based realms defined, `realm1` and `realm2`, we would define a `resourcePath` for each, in the form: - -[source,ini] ----- -realm1.resourcePath=classpath:webapp/realm1.ini ----- - -that is, the `src/main/resources/webapp/realm1.ini` file in the webapp project. - -The security manager for the app would then be told to use these two realms: - -[source,ini] ----- -securityManager.realms = $realm1,$realm2 ----- - -The the `[users]` and `[roles]` sections of `shiro.ini` would then be unused. Instead, you'll find these sections in both `realm1.ini` and `realm2.ini` (because both are coincidentally implementations of the same `org.apache.shiro.realm.text.IniRealm` class). - - - - -== Configuring Shiro to use LDAP - -Isis ships with an implementation of http://shiro.apache.org[Apache Shiro]'s `Realm` class that allows user authentication and authorization to be performed against an LDAP server. - -The configuration required in the `WEB-INF/shiro.ini` file is: - -[source,ini] ----- -contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory -contextFactory.url = ldap://localhost:10389 -contextFactory.systemUsername = uid=admin,ou=system # <1> -contextFactory.systemPassword = secret -contextFactory.authenticationMechanism = CRAM-MD5 # <2> -contextFactory.systemAuthenticationMechanism = simple - -ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm -ldapRealm.contextFactory = $contextFactory - -ldapRealm.searchBase = ou=groups,o=mojo # <3> -ldapRealm.groupObjectClass = groupOfUniqueNames # <4> -ldapRealm.uniqueMemberAttribute = uniqueMember # <5> -ldapRealm.uniqueMemberAttributeValueTemplate = uid={0} - -# optional mapping from physical groups to logical application roles -ldapRealm.rolesByGroup = \ # <6> - LDN_USERS: user_role,\ - NYK_USERS: user_role,\ - HKG_USERS: user_role,\ - GLOBAL_ADMIN: admin_role,\ - DEMOS: self-install_role - -ldapRealm.permissionsByRole=\ # <7> - user_role = *:ToDoItemsJdo:*:*,\ - *:ToDoItem:*:*; \ - self-install_role = *:ToDoItemsFixturesService:install:* ; \ - admin_role = * - -securityManager.realms = $ldapRealm ----- -<1> user accounts are searched using a dedicated service account -<2> SASL (CRAM-MD5) authentication is used for this authentication -<3> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name) -<4> each group has an LDAP objectClass of `groupOfUniqueNames` -<5> each group has a vector attribute of `uniqueMember` -<6> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly -<7> roles are mapped in turn to permissions - -The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user -* users searched under `ou=system` -* users have, at minimum, a `uid` attribute and a password -* the users credentials are used to verify their user/password - -The above configuration has been tested against http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be administered using http://directory.apache.org/studio/[Apache Directory Studio], v1.5.3. - - - -=== Using a shared role/perms path - -As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path: - -[source,ini] ----- -ldapRealm.resourcePath=classpath:webapp/myroles.ini ----- - -where `myroles.ini` is in `src/main/resources/webapp`, and takes the form: - -[source,ini] ----- - [roles] - user_role = *:ToDoItemsJdo:*:*,\ - *:ToDoItem:*:* - self-install_role = *:ToDoItemsFixturesService:install:* - admin_role = * ----- - -This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm) - - -=== Active DS LDAP Configuration - -The screenshot below shows the ApacheDS using Apache Directory Studio. The setup here was initially base on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial]. However, user accounts have been moved to a separate node. - -==== Configure Mojo partition and nodes under Root - -Create a partition in order to hold the mojo node (holding the groups) - -image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users] - -Create the `ou=groups,o=mojo` hierarchy - -image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS LDAP Users] - -Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Isis connecting to LDAP using these credentials. - -image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS LDAP Users] - -In order for SASL to work, it seems to be necessary to put users under `o=system`. (This is why the setup is slightly different than the tutorial mentioned above). - -image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS LDAP Users] - -Configure the users into the groups. - -image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS LDAP Users] - - -== Shiro Realm Mappings - -When configuring role based permission mapping, there can only be one of these entries per realm: - -[source] ----- -realm.groupToRolesMappings = ... ----- - -and - -[source] ----- -realm.roleToPermissionsMappings = ... ----- - -This forces you to put everything on one line for each of the above. - -This is, unfortunately, a Shiro "feature". The only solution to this is to use "\" to separate the mappings onto separate lines in the file so that it is at least maintainable. - -Use this technique for both group to roles mapping and role to permission mapping. If you use the '' after the "," that separates the key:value pairs it is more readable. - -If you repeat the entries above then it's "last one wins". - -[WARNING] -==== -Configuring a [roles] section instead doesn't work because that triggers Shiro to use the simple "INI" realm and not your defined realm. - -In an enterprise environment you are most likely going to use either an LDAP realm or the realm that comes with the http://github.com/isisaddons/isis-module-security}[Isis addons' security] module (non-ASF); so the "simple" realm in Shiro isn't much use beyond prototyping work). -==== - - - -== Configuring Shiro to use the Security Isis Addons - -The Isisaddons https://github.com/isisaddons/isis-module-security[security module] (not ASF) provides a complete -security subdomain for users, roles, permissions; all persisted as JDO domain objects. It also includes a Shiro realm -integration. - -See the module's README for details of how to configure an existing app to use this module. Or, look at the the -Isisaddons https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), which is preconfigured to use -the security module. - - - -== Configuring Shiro for JDBC - -Something like the following should do: - -[source,ini] ----- -builtInCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager -securityManager.cacheManager = $builtInCacheManager - -ps = org.apache.shiro.authc.credential.DefaultPasswordService -pm = org.apache.shiro.authc.credential.PasswordMatcher -pm.passwordService = $ps - -aa = org.apache.shiro.authc.credential.AllowAllCredentialsMatcher -sm = org.apache.shiro.authc.credential.SimpleCredentialsMatcher - -jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm -jdbcRealm.authenticationQuery = SELECT password from users where username = ? -jdbcRealm.userRolesQuery = select r.label from users_roles ur inner join roles r on ur.role_id = r.id where user_id = (select id from users where username = ?); -jdbcRealm.permissionsQuery=select p.permission from roles_permissions rp inner join permissions p on rp.permission_id = p.id where rp.role_id = (select id from roles where label = ?); -jdbcRealm.permissionsLookupEnabled=true - -ds = com.mysql.jdbc.jdbc2.optional.MysqlDataSource -ds ...etc -securityManager.realms = $jdbcRealm ----- - -However, we would recommend you consider using the http://github.com/isisaddons/isis-module-security}[Isis addons' security] module instead of a home-grown JDBC solution. - - - -== Accessing user/roles from domain objects - -Generally speaking your domain objects should be agnostic of the user/roles that are interacting with them; applying security permissions is the responsibility of the framework. - -Still, on very rare occasion you may have a need, in which case use the `DomainObjectContainer` service: - -[source,java] ----- -final UserMemento user = container.getUser(); -final List<RoleMemento> roles = user.getRoles(); -for (RoleMemento role : roles) { - String roleName = role.getName(); - ... -} ----- - -Each role's `name` property encodes both the realm that provided the role, and the role identity itself. - -For example, in the simpleapp, if logging in as `dick` with the following entries for `realm1`: - -[source,ini] ----- -dick = pass, user_role, analysis_role, self-install_role ----- - -then this corresponds to the roles "realm1:user_role", "realm1:self-install_role" and "realm1:analysis_role". - -If using the Wicket viewer, then there will also be another role which is used internally (namely "org.apache.isis.viewer.wicket.roles.USER"). - - - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_files.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_files.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_files.adoc deleted file mode 100644 index c5ddffe..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_files.adoc +++ /dev/null @@ -1,87 +0,0 @@ -= Configuration Files -: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/ - - -When running an Isis webapp, configuration properties are read from configuration files held in the `WEB-INF` directory. - -The `WEBINF/isis.properties` file is always read and must exist. - -In addition, the following other properties are searched for and if present also read: - -* `viewer_wicket.properties` - if the <<_wicket_viewer_2, Wicket UI (viewer)>> is in use - -* `viewer_restfulobjects.properties` - if the <<_restful_objects_viewer, Restful Objects REST API (viewer)>> is in use - -* `viewer.properties` - for any shared UI configuration - -* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use - -* `persistor.properties` - for any other objectstore configuration. This typically is used to hold `JDBC` ``URL``s - -* `authentication_shiro.properties`, `authorization_shiro.properties` -+ -assuming the Shiro Security is in use (but there are no security-related config properties currently; use shiro.ini for Shiro config) - -* `authentication.properties`, `authorization.properties` + -+ -for any other security-related config properties (but there are none currently). - -You can if you wish simply store all properties in the `isis.properties` file; but we think that breaking properties out into sections is preferable. - - -== Specifying other components - -The `isis.properties` file has three configuration properties in particular that specify the major components of Isis to use. They are: - -.Core Configuration Properties -[cols="2a,1,3a", options="header"] -|=== -|Property -|Value + -(_default value_) -|Implements - -|`isis.persistor` -|`_datanucleus_` -|`org.apache.isis.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller` - -|`isis.authentication` -|`_shiro_` + -`bypass` -|`org.apache.isis.core.runtime.authentication.` `AuthenticationManagerInstaller` - -|`isis.authorization` -|`_shiro_` + -`bypass` -|`org.apache.isis.core.runtime.authorization.` `AuthorizationManagerInstaller` - -|=== - -[TIP] -==== -The values "datanucleus", "shiro" etc are actually aliases for concrete implementations listed in Isis' `installer-registry.properties` file (in `isis-core-runtime.jar`). It is -- at least in theory -- possible to specify a fully qualified class name to replace any of these components. In practice only the two security APIs are actually simple enough for this to be viable. -==== - -As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed <<_configuring_the_webapp, below>>). However, the configuration of which viewers to initialize is declared through a context parameter: - - -[source,xml] ----- -<context-param> - <param-name>isis.viewers</param-name> - <param-value>wicket,restfulobjects</param-value> -</context-param> ----- - -The net effect of this configuration is simply to ensure that the `viewer_wicket.properties` and/or the `viewer_restfulobjects.properties` files are read. - - - -== Deployment Types - -IMPORTANT: TODO - - - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_integration-tests.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_integration-tests.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_integration-tests.adoc deleted file mode 100644 index 7766d86..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_integration-tests.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Configuring Integration Tests -: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 - -Integration tests are configured programmatically, with a default set of properties to bootstrap the JDO/DataNucleus objectstore using an HSQLDB in-memory database. - -These can be overridden by subclassing `IsisConfigurationForJdoIntegTests`. - - - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties.adoc deleted file mode 100644 index 570d24f..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties.adoc +++ /dev/null @@ -1,15 +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/ - -This section lists the configuration properties recognized by Apache Isis. - -include::_user-guide_configuration_properties_core.adoc[leveloffset=+1] - -include::_user-guide_configuration_properties_wicket-viewer.adoc[leveloffset=+1] - -include::_user-guide_configuration_properties_restfulobjects-viewer.adoc[leveloffset=+1] - -include::_user-guide_configuration_properties_datanucleus-objectstore.adoc[leveloffset=+1] - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_core.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_core.adoc deleted file mode 100644 index ff525c0..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_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/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_datanucleus-objectstore.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_datanucleus-objectstore.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_datanucleus-objectstore.adoc deleted file mode 100644 index 2c6ba58..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_datanucleus-objectstore.adoc +++ /dev/null @@ -1,57 +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>>. - -|=== - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_restfulobjects-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_restfulobjects-viewer.adoc deleted file mode 100644 index a932663..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_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/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_wicket-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_properties_wicket-viewer.adoc deleted file mode 100644 index e613d3a..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_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/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_web-xml.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_web-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_web-xml.adoc deleted file mode 100644 index 8be8f26..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_configuration_web-xml.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= `web.xml` -: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 - - -== Init Params - -`<isis.viewers>` - -== Filters - - -== Servlets - - -== Running Restful Objects Viewer only \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc index fb3f94e..26fdede 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc @@ -5,10 +5,14 @@ This chapter provides guidance on some common deployment scenarios. +include::_user-guide_deployment_cmd-line.adoc[leveloffset=+1] + include::_user-guide_deployment_tomcat.adoc[leveloffset=+1] include::_user-guide_deployment_gae.adoc[leveloffset=+1] +include::_user-guide_deployment_jvm-flags.adoc[leveloffset=+1] + http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc new file mode 100644 index 0000000..5c936d6 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc @@ -0,0 +1,29 @@ += Command Line +: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 + + +## `WebServer` class + +`org.apache.isis.WebServer` + +For example: +* `--fixture` +* `--services` + +etc... + + + +## `Dummy` class + +`org.apache.isis.Dummy` + + +etc... + + + http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc new file mode 100644 index 0000000..d359f52 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc @@ -0,0 +1,18 @@ += JVM Flags +: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 + + +for the `WrapperFactory` (uses link:http://www.csg.ci.i.u-tokyo.ac.jp/~chiba/javassist/[Javassist]) + +using: + +[source] +---- +-XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC +---- + +You can hint the JVM to unload dynamically created classes which ClassLoaders are still around. http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc index 54dcc25..1250a72 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc @@ -5,11 +5,11 @@ IMPORTANT: TODO -## Disallowing deprecated annotations +== Disallowing deprecated annotations -## Custom validator +== Custom validator -## Finetuning the Programming Model +== Finetuning the Programming Model -## Layout metadata reader +== Layout metadata reader http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc index 51d75a3..84b2e84 100644 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc +++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc @@ -4,8 +4,29 @@ :_imagesdir: images/ +The Wicket viewer allows you to customize the GUI in several (progressively more sophisticated) ways: + +* by <<_tweak_the_ui_with_css, tweaking the UI using CSS>> +* by <<_tweak_the_ui_with_javascript, tweaking the UI using Javascript>> +* by writing a <<_writing_a_custom_theme, custom bootstrap theme>> +* by <<_replacing_page_elements, replacing elements of the page>> using the `ComponentFactory` interface +* by implementing <<_custom_pages, replacement page implementations>> for the standard page types + +This chapter describes each of these mechanisms. + + +== Tweak the UI with CSS + +IMPORTANT: TODO + + + +== Tweak the UI with Javascript + IMPORTANT: TODO + + == Writing a custom theme IMPORTANT: TODO @@ -15,14 +36,226 @@ IMPORTANT: TODO == Replacing page elements -IMPORTANT: TODO +Replacing elements of the page is the most powerful general-purpose way to customize the look-n-feel of the viewer. Examples at http://www.isisaddons.org[Isis Add-ons] include the link:isisaddons/isis-wicket-gmap3.html[gmap3], link:isisaddons/isis-wicket-fullcalendar2.html[calendar], link:isisaddons/isis-wicket-excel.html[excel download] and link:isisaddons/isis-wicket-wickedcharts.html[charting] integrations. + +The pages generated by Isis' Wicket viewer are built up of numerous elements, from fine-grained widgets for property/parameter fields, to much larger components that take responsibility for rendering an entire entity entity, or a collection of entities. Under the covers these are all implementations of the the Apache Wicket `Component` API. The larger components delegate to the smaller, of course. + +=== How the Wicket viewer selects components + +Components are created using Isis' `ComponentFactory` interface, which are registered in turn through the `ComponentFactoryRegistrar` interface. Every component is categorizes by type (the `ComponentType` enum), and Isis uses this to determine which `ComponentFactory` to use. For example, the `ComponentType.BOOKMARKED_PAGES` is used to locate the `ComponentFactory` that will build the bookmarked pages panel. + +Each factory is also handed a model (an implementation of `org.apache.wicket.IModel`) appropriate to its `ComponentType`; this holds the data to be rendered. For example, `ComponentType.BOOKMARKED_PAGES` is given a `BookmarkedPagesModel`, while `ComponentType.SCALAR_NAME_AND_VALUE` factories are provided a model of type of type `ScalarModel` . + +In some cases there are several factories for a given `ComponentType`; this is most notably the case for `ComponentType.SCALAR_NAME_AND_VALUE`. After doing a first pass selection of candidate factories by `ComponentType`, each factory is then asked if it `appliesTo(Model)`. This is an opportunity for the factory to check the model itself to see if the data within it is of the appropriate type. + +Thus, the `BooleanPanelFactory` checks that the `ScalarModel` holds a boolean, while the `JodaLocalDatePanelFactory` checks to see if it holds `org.joda.time.LocalDate`. +There will typically be only one `ComponentFactory` capable of rendering a particular `ComponentType`/`ScalarModel` combination; at any rate, the framework stops as soon as one is found. + +[NOTE] +==== +There is one refinement to the above algorithm where multiple component factories might be used to render an object; this is discussed in <<Additional Views of Collections>>, below. +==== + + +=== How to replace a component + +This design (the http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern[chain of responsibility] design pattern) makes it quite straightforward to change the rendering of any element of the page. For example, you might switch out Isis' sliding bookmark panel and replace it with one that presents the bookmarks in some different fashion. + +First, you need to write a `ComponentFactory` and corresponding `Component`. The recommended approach is to start with the source of the `Component` you want to switch out. For example: + +[source,java] +---- +public class MyBookmarkedPagesPanelFactory extends ComponentFactoryAbstract { + public MyBookmarkedPagesPanelFactory() { + super(ComponentType.BOOKMARKED_PAGES); + } + @Override + public ApplicationAdvice appliesTo(final IModel<?> model) { + return appliesIf(model instanceof BookmarkedPagesModel); + } + @Override + public Component createComponent(final String id, final IModel<?> model) { + final BookmarkedPagesModel bookmarkedPagesModel = (BookmarkedPagesModel) model; + return new MyBookmarkedPagesPanel(id, bookmarkedPagesModel); + } +} +---- + +and + +[source,java] +---- +public class MyBookmarkedPagesPanel + extends PanelAbstract<BookmarkedPagesModel> { + ... +} +---- + +Here `PanelAbstract` ultimately inherits from `org.apache.wicket.Component`. +Your new `Component` uses the information in the provided model (eg `BookmarkedPagesModel`) to know what to render. + +Next, you will require a custom implementation of the `ComponentFactoryRegistrar` that registers your custom `ComponentFactory` as a replacement: + +[source,java] +---- +@Singleton +public class MyComponentFactoryRegistrar extends ComponentFactoryRegistrarDefault { + @Override + public void addComponentFactories(ComponentFactoryList componentFactories) { + super.addComponentFactories(componentFactories); + componentFactories.add(new MyBookmarkedPagesPanelFactory()); + } +} +---- + +This will result in the new component being used instead of (that is, discovered prior to) Isis' default implementation. + +[WARNING] +==== +Previously we suggested using "replace" rather than "add"; however this has unclear semantics for some component types; see https://issues.apache.org/jira/browse/ISIS-996[ISIS-996]. +==== + + +Finally (as for other customizations), you need to adjust the Guice bindings in your custom subclass of `IsisWicketApplication`: + +[source,java] +---- +public class MyAppApplication extends IsisWicketApplication { + @Override + protected Module newIsisWicketModule() { + final Module isisDefaults = super.newIsisWicketModule(); + final Module myAppOverrides = new AbstractModule() { + @Override + protected void configure() { + ... + bind(ComponentFactoryRegistrar.class) + .to(MyComponentFactoryRegistrar.class); + ... + } + }; + + return Modules.override(isisDefaults).with(myAppOverrides); + } +} +---- + +=== Additional Views of Collections + +As explained above, in most cases Isis' Wicket viewer will search for the first `ComponentFactory` that can render an element, and use it. In the case of (either standalone or parented) collections, though, Isis will show all available views. + +For example, out-of-the-box Isis provides a table view, a summary view (totals/sums/averages of any data), and a collapsed view (for `@Render(LAZILY)` collections). These are selected by clicking on the toolbar by each collection. + +Additional views though could render the objects in the collection as a variety of ways. Indeed, some third-party implementations already exist: + +* https://github.com/isisaddons/isis-wicket-excel[excel integration] (collection as a downloadable excel spreadsheet) +* https://github.com/isisaddons/isis-wicket-gmap3[google maps v3 integration] (render any objects with a location on a map) +* https://github.com/isisaddons/isis-wicket-wickedcharts[wicked charts integration] (barchart of any data) +* https://github.com/isisaddons/isis-wicket-fullcalendar2[full calendar integration] (render any objects with date properties on a calendar) + +Registering these custom views is just a matter of adding the appropriate Maven module to the classpath. Isis uses the JDK `ServiceLoader` API to automatically discover and register the `ComponentFactory` of each such component. + +If you want to write your own alternative component and auto-register, then include a file `META-INF/services/org.apache.isis.viewer.wicket.ui.ComponentFactory` whose contents is the fully-qualified class name of the custom `ComponentFactory` that you have written. + +Wicket itself has lots of components available at its http://wicketstuff.org[wicketstuff.org] companion website; you might find some of these useful for your own customizations. + +=== Adding a Custom Object View (eg a Dashboard) + +One further use case in particular is worth highlighting; the rendering of an entire entity. Normally entities this is done using `EntityCombinedPanelFactory`, this being the first `ComponentFactory` for the `ComponentType.ENTITY` that is registered in Isis default `ComponentFactoryRegistrarDefault`. + +You could, though, register your own `ComponentFactory` for entities that is targeted at a particular class of entity - some sort of object representing a dashboard, for example. It can use the `EntityModel` provided to it to determine the class of the entity, checking if it is of the appropriate type. Your custom factory should also be registered before the `EntityCombinedPanelFactory` so that it is checked prior to the default `EntityCombinedPanelFactory`: + +[source,java] +---- +@Singleton +public class MyComponentFactoryRegistrar extends ComponentFactoryRegistrarDefault { + @Override + public void addComponentFactories(ComponentFactoryList componentFactories) { + componentFactories.add(new DashboardEntityFactory()); + ... + super.addComponentFactories(componentFactories); + ... + } +} +---- == Custom pages -IMPORTANT: TODO +In the vast majority of cases customization should be sufficient by link:./customizing-the-viewer.html[replacing elements of a page]. However, it is also possible to define an entirely new page for a given page type. + +Isis defines eight page types (see the `org.apache.isis.viewer.wicket.model.models.PageType` enum): + +.PageType enum +[cols="1,4", options="header"] +|=== +| Page type +| Renders + +| SIGN_IN +| The initial sign-in page + +| HOME +| The home page, displaying either the welcome message or dashboard + +| ABOUT +| The about page, accessible from link top-right + +| ENTITY +| Renders a single entity or view model + +| STANDALONE_COLLECTION +| Page rendered after invoking an action that returns a collection of entites + +| VALUE +| After invoking an action that returns a value type (though not URLs or Blob/Clobs, as these are handled appropriately automatically). + +| VOID_RETURN +| After invoking an action that is `void` + +| ACTION_PROMPT +| (No longer used). + +|=== + + +The `PageClassList` interface declares which class (subclass of `org.apache.wicket.Page` is used to render for each of these types. For example, Isis' `WicketSignInPage` renders the signin page. + +To specify a different page class, create a custom subclass of `PageClassList`: + +[source,java] +---- +@Singleton +public class MyPageClassList extends PageClassListDefault { + protected Class<? extends Page> getSignInPageClass() { + return MySignInPage.class; + } +} +---- + + +You then need to register your custom `PageClassList`. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`: + +[source,java] +---- +public class MyAppApplication extends IsisWicketApplication { + @Override + protected Module newIsisWicketModule() { + final Module isisDefaults = super.newIsisWicketModule(); + final Module myAppOverrides = new AbstractModule() { + @Override + protected void configure() { + ... + bind(PageClassList.class).to(MyPageClassList.class); + ... + } + }; + return Modules.override(isisDefaults).with(myAppOverrides); + } +} +---- + http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/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 8a7ebf2..57de31d 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 @@ -17,7 +17,3 @@ include::_user-guide_reference_applib-utility-classes.adoc[leveloffset=+1] include::_user-guide_reference_convenience-superclasses.adoc[leveloffset=+1] -include::_user-guide_reference_cmd-line-args.adoc[leveloffset=+1] - -include::_user-guide_reference_web-xml.adoc[leveloffset=+1] - http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_cmd-line-args.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_cmd-line-args.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_cmd-line-args.adoc deleted file mode 100644 index 4e52124..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_cmd-line-args.adoc +++ /dev/null @@ -1,31 +0,0 @@ -= Command Line Arguments -: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 - - -## `org.apache.isis.WebServer` - -For example: -* `--fixture` -* `--services` - -etc... - - - -## Recommended JVM Flags - - -for the `WrapperFactory` (uses link:http://www.csg.ci.i.u-tokyo.ac.jp/~chiba/javassist/[Javassist]) - -using: - -[source] ----- --XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC ----- - -You can hint the JVM to unload dynamically created classes which ClassLoaders are still around. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/3cd72ab9/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_web-xml.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_web-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_web-xml.adoc deleted file mode 100644 index bc6da88..0000000 --- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_web-xml.adoc +++ /dev/null @@ -1,8 +0,0 @@ -= web.xml Configuration -: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 - -
