From 66b4dec86a1e7751ec91af0b9ca814065b83449e Mon Sep 17 00:00:00 2001 From: Lagom Build Server Date: Thu, 10 Mar 2016 17:06:38 -0800 Subject: [PATCH] Updating 1.0.x documentation --- documentation/1.0.x/Cluster.html | 2 +- documentation/1.0.x/ConductR.html | 3 +- documentation/1.0.x/Home.html | 3 + documentation/1.0.x/Overview.html | 1 + documentation/1.0.x/ReactivePlatform.html | 164 ++++++++ documentation/1.0.x/ReferenceGuide.html | 3 + .../1.0.x/api/java/allclasses-frame.html | 27 +- .../1.0.x/api/java/allclasses-noframe.html | 27 +- .../discovery/ServiceAlreadyRegistered.html | 4 +- .../lagom/discovery/ServiceLocatorServer.html | 4 +- .../discovery/ServiceRegistryActor$.html | 4 +- .../ServiceRegistryActor.Found$.html | 4 +- .../discovery/ServiceRegistryActor.Found.html | 4 +- ...eRegistryActor.GetRegisteredServices$.html | 4 +- .../ServiceRegistryActor.Lookup$.html | 4 +- .../ServiceRegistryActor.Lookup.html | 4 +- .../ServiceRegistryActor.NotFound$.html | 4 +- .../ServiceRegistryActor.NotFound.html | 4 +- .../ServiceRegistryActor.Register$.html | 4 +- .../ServiceRegistryActor.Register.html | 4 +- ...viceRegistryActor.RegisteredServices$.html | 4 +- ...rviceRegistryActor.RegisteredServices.html | 4 +- .../ServiceRegistryActor.Remove$.html | 4 +- .../ServiceRegistryActor.Remove.html | 4 +- .../ServiceRegistryActor.Route$.html | 4 +- .../discovery/ServiceRegistryActor.Route.html | 4 +- .../ServiceRegistryActor.RouteResult.html | 4 +- .../lagom/discovery/ServiceRegistryActor.html | 4 +- .../lagom/discovery/UnmanagedServices$.html | 4 +- .../lagom/discovery/UnmanagedServices.html | 4 +- .../discovery/impl/ServiceRegistryImpl.html | 4 +- .../discovery/impl/ServiceRegistryModule.html | 4 +- .../lagom/discovery/impl/package-frame.html | 4 +- .../lagom/discovery/impl/package-summary.html | 4 +- .../lagom/discovery/impl/package-tree.html | 4 +- .../lagom/discovery/package-frame.html | 4 +- .../lagom/discovery/package-summary.html | 4 +- .../lagom/discovery/package-tree.html | 4 +- .../lagom/gateway/ServiceGateway.html | 4 +- .../lagom/gateway/ServiceGatewayConfig$.html | 4 +- .../lagom/gateway/ServiceGatewayConfig.html | 4 +- .../lagom/gateway/package-frame.html | 4 +- .../lagom/gateway/package-summary.html | 4 +- .../lightbend/lagom/gateway/package-tree.html | 4 +- .../lagom/javadsl/api/Descriptor.Call.html | 4 +- .../lagom/javadsl/api/Descriptor.CallId.html | 4 +- .../api/Descriptor.CircuitBreakerId.html | 4 +- .../javadsl/api/Descriptor.NamedCallId.html | 4 +- .../javadsl/api/Descriptor.PathCallId.html | 4 +- .../javadsl/api/Descriptor.RestCallId.html | 4 +- .../lagom/javadsl/api/Descriptor.html | 4 +- .../Service.SelfDescribingServiceCall.html | 4 +- .../lightbend/lagom/javadsl/api/Service.html | 4 +- .../lagom/javadsl/api/ServiceAcl.html | 4 +- .../lagom/javadsl/api/ServiceCall.html | 4 +- .../lagom/javadsl/api/ServiceInfo.html | 4 +- .../lagom/javadsl/api/ServiceLocator.html | 4 +- .../api/deser/DeserializationException.html | 4 +- .../javadsl/api/deser/ExceptionMessage.html | 4 +- .../api/deser/ExceptionSerializer.html | 4 +- .../lagom/javadsl/api/deser/IdSerializer.html | 70 ++-- .../javadsl/api/deser/IdSerializers.html | 75 +--- ...sageSerializer.NegotiatedDeserializer.html | 4 +- ...essageSerializer.NegotiatedSerializer.html | 4 +- .../javadsl/api/deser/MessageSerializer.html | 4 +- .../javadsl/api/deser/MessageSerializers.html | 4 +- .../api/deser/RawExceptionMessage.html | 4 +- .../javadsl/api/deser/RawId.PathParam.html | 135 ++++--- .../lagom/javadsl/api/deser/RawId.html | 370 ++++++++++++++---- .../javadsl/api/deser/RawIdDescriptor.html | 8 +- .../api/deser/SerializationException.html | 4 +- .../javadsl/api/deser/SerializerFactory.html | 4 +- .../api/deser/StreamedMessageSerializer.html | 4 +- .../api/deser/StrictMessageSerializer.html | 4 +- .../javadsl/api/deser/package-frame.html | 5 +- .../javadsl/api/deser/package-summary.html | 12 +- .../lagom/javadsl/api/deser/package-tree.html | 5 +- .../lagom/javadsl/api/package-frame.html | 4 +- .../lagom/javadsl/api/package-summary.html | 4 +- .../lagom/javadsl/api/package-tree.html | 4 +- .../lagom/javadsl/api/paging/Page.html | 4 +- .../javadsl/api/paging/package-frame.html | 4 +- .../javadsl/api/paging/package-summary.html | 4 +- .../javadsl/api/paging/package-tree.html | 4 +- .../api/security/ServicePrincipal.html | 4 +- ...serAgentServiceIdentificationStrategy.html | 4 +- .../javadsl/api/security/package-frame.html | 4 +- .../javadsl/api/security/package-summary.html | 4 +- .../javadsl/api/security/package-tree.html | 4 +- .../javadsl/api/transport/Forbidden.html | 4 +- .../api/transport/HeaderTransformer.html | 4 +- .../javadsl/api/transport/MessageHeader.html | 4 +- .../api/transport/MessageProtocol.html | 4 +- .../lagom/javadsl/api/transport/Method.html | 4 +- .../javadsl/api/transport/NotAcceptable.html | 4 +- .../lagom/javadsl/api/transport/NotFound.html | 4 +- ...hVersionedProtocolNegotiationStrategy.html | 4 +- .../api/transport/PayloadTooLarge.html | 4 +- .../api/transport/PolicyViolation.html | 4 +- .../javadsl/api/transport/RequestHeader.html | 4 +- .../javadsl/api/transport/ResponseHeader.html | 4 +- .../api/transport/TransportErrorCode.html | 4 +- .../api/transport/TransportException.html | 4 +- .../api/transport/UnsupportedMediaType.html | 4 +- .../javadsl/api/transport/package-frame.html | 4 +- .../api/transport/package-summary.html | 4 +- .../javadsl/api/transport/package-tree.html | 4 +- .../client/ServiceClientGuiceSupport.html | 4 +- .../lagom/javadsl/client/package-frame.html | 4 +- .../lagom/javadsl/client/package-summary.html | 4 +- .../lagom/javadsl/client/package-tree.html | 4 +- .../cluster/testkit/ActorSystemModule.html | 4 +- .../cluster/testkit/package-frame.html | 4 +- .../cluster/testkit/package-summary.html | 4 +- .../javadsl/cluster/testkit/package-tree.html | 4 +- .../javadsl/immutable/ImmutableStyle.html | 4 +- .../javadsl/immutable/package-frame.html | 4 +- .../javadsl/immutable/package-summary.html | 4 +- .../lagom/javadsl/immutable/package-tree.html | 4 +- .../jackson/JacksonExceptionSerializer.html | 4 +- .../lagom/javadsl/jackson/JacksonModule.html | 4 +- .../jackson/JacksonSerializerFactory.html | 4 +- .../lagom/javadsl/jackson/package-frame.html | 4 +- .../javadsl/jackson/package-summary.html | 4 +- .../lagom/javadsl/jackson/package-tree.html | 4 +- .../javadsl/persistence/AggregateEvent.html | 4 +- .../persistence/AggregateEventTag$.html | 4 +- .../persistence/AggregateEventTag.html | 4 +- .../javadsl/persistence/CommandEnvelope$.html | 4 +- .../javadsl/persistence/CommandEnvelope.html | 4 +- .../InitServiceLocatorHolder$.html | 4 +- .../persistence/InitServiceLocatorHolder.html | 4 +- .../persistence/PersistenceModule.html | 4 +- .../persistence/PersistentEntity$.html | 4 +- .../PersistentEntity.Behavior$.html | 4 +- .../PersistentEntity.Behavior.html | 4 +- .../PersistentEntity.CommandContext.html | 4 +- ...istentEntity.InvalidCommandException$.html | 4 +- ...sistentEntity.InvalidCommandException.html | 4 +- .../persistence/PersistentEntity.Persist.html | 4 +- .../PersistentEntity.PersistAll$.html | 4 +- .../PersistentEntity.PersistAll.html | 4 +- .../PersistentEntity.PersistException$.html | 4 +- .../PersistentEntity.PersistException.html | 4 +- .../PersistentEntity.PersistNone.html | 4 +- .../PersistentEntity.PersistOne$.html | 4 +- .../PersistentEntity.PersistOne.html | 4 +- ...rsistentEntity.ReadOnlyCommandContext.html | 4 +- .../PersistentEntity.ReplyType.html | 4 +- ...tentEntity.UnhandledCommandException$.html | 4 +- ...stentEntity.UnhandledCommandException.html | 4 +- .../javadsl/persistence/PersistentEntity.html | 4 +- .../persistence/PersistentEntityRef.html | 4 +- .../persistence/PersistentEntityRegistry.html | 4 +- .../cassandra/CassandraReadSide.html | 4 +- ...sandraReadSideProcessor.EventHandlers.html | 4 +- ...eadSideProcessor.EventHandlersBuilder.html | 4 +- .../cassandra/CassandraReadSideProcessor.html | 4 +- .../cassandra/CassandraSession.html | 4 +- .../persistence/cassandra/package-frame.html | 4 +- .../cassandra/package-summary.html | 4 +- .../persistence/cassandra/package-tree.html | 4 +- .../javadsl/persistence/package-frame.html | 4 +- .../javadsl/persistence/package-summary.html | 4 +- .../javadsl/persistence/package-tree.html | 4 +- .../persistence/testkit/TestUtil$.html | 4 +- .../TestUtil.AwaitPersistenceInit.html | 4 +- .../javadsl/persistence/testkit/TestUtil.html | 8 +- .../persistence/testkit/package-frame.html | 29 +- .../persistence/testkit/package-summary.html | 106 +---- .../persistence/testkit/package-tree.html | 41 +- .../lagom/javadsl/pubsub/PubSubModule.html | 4 +- .../lagom/javadsl/pubsub/PubSubRef.html | 4 +- .../lagom/javadsl/pubsub/PubSubRegistry.html | 4 +- .../lagom/javadsl/pubsub/TopicId$.html | 4 +- .../lagom/javadsl/pubsub/TopicId.html | 4 +- .../lagom/javadsl/pubsub/package-frame.html | 4 +- .../lagom/javadsl/pubsub/package-summary.html | 4 +- .../lagom/javadsl/pubsub/package-tree.html | 4 +- .../javadsl/server/HeaderServiceCall.html | 4 +- .../lagom/javadsl/server/PlayServiceCall.html | 4 +- .../javadsl/server/ServerServiceCall.html | 4 +- ...rviceGuiceSupport.ClassServiceBinding.html | 4 +- ...ceGuiceSupport.InstanceServiceBinding.html | 4 +- .../ServiceGuiceSupport.ServiceBinding.html | 4 +- .../javadsl/server/ServiceGuiceSupport.html | 4 +- .../lagom/javadsl/server/package-frame.html | 4 +- .../lagom/javadsl/server/package-summary.html | 4 +- .../lagom/javadsl/server/package-tree.html | 4 +- .../status/AbstractCircuitBreakerStatus.html | 4 +- .../server/status/AbstractLatency.html | 4 +- .../status/CircuitBreakerStatus.Builder.html | 4 +- .../server/status/CircuitBreakerStatus.html | 4 +- .../server/status/Latency.Builder.html | 4 +- .../lagom/javadsl/server/status/Latency.html | 4 +- .../javadsl/server/status/MetricsService.html | 4 +- .../javadsl/server/status/package-frame.html | 4 +- .../server/status/package-summary.html | 4 +- .../javadsl/server/status/package-tree.html | 4 +- .../testkit/PersistentEntityTestDriver$.html | 4 +- .../PersistentEntityTestDriver.Issue.html | 4 +- ...sistentEntityTestDriver.NoSerializer$.html | 4 +- ...rsistentEntityTestDriver.NoSerializer.html | 4 +- ...ntEntityTestDriver.NotDeserializable$.html | 4 +- ...entEntityTestDriver.NotDeserializable.html | 4 +- ...estDriver.NotEqualAfterSerialization$.html | 4 +- ...TestDriver.NotEqualAfterSerialization.html | 4 +- ...tentEntityTestDriver.NotSerializable$.html | 4 +- ...stentEntityTestDriver.NotSerializable.html | 4 +- .../PersistentEntityTestDriver.Outcome$.html | 4 +- .../PersistentEntityTestDriver.Outcome.html | 4 +- .../PersistentEntityTestDriver.Reply$.html | 4 +- .../PersistentEntityTestDriver.Reply.html | 4 +- ...PersistentEntityTestDriver.SideEffect.html | 4 +- ...entEntityTestDriver.UnhandledCommand$.html | 4 +- ...tentEntityTestDriver.UnhandledCommand.html | 4 +- ...stentEntityTestDriver.UnhandledEvent$.html | 4 +- ...istentEntityTestDriver.UnhandledEvent.html | 4 +- ...EntityTestDriver.UsingJavaSerializer$.html | 4 +- ...tEntityTestDriver.UsingJavaSerializer.html | 4 +- .../testkit/PersistentEntityTestDriver.html | 4 +- .../lagom/javadsl/testkit/ServiceTest$.html | 4 +- .../javadsl/testkit/ServiceTest.Setup$.html | 4 +- .../javadsl/testkit/ServiceTest.Setup.html | 4 +- .../testkit/ServiceTest.TestServer.html | 4 +- .../lagom/javadsl/testkit/ServiceTest.html | 4 +- .../lagom/javadsl/testkit/package-frame.html | 4 +- .../javadsl/testkit/package-summary.html | 4 +- .../lagom/javadsl/testkit/package-tree.html | 4 +- .../lightbend/lagom/play/LagomPlayModule.html | 4 +- .../play/PlayRegisterWithServiceRegistry.html | 4 +- .../lagom/play/PlayServiceInfoProvider.html | 4 +- .../lightbend/lagom/play/package-frame.html | 4 +- .../lightbend/lagom/play/package-summary.html | 4 +- .../lightbend/lagom/play/package-tree.html | 4 +- .../serialization/CompressedJsonable.html | 4 +- .../serialization/JacksonJsonMigration.html | 4 +- .../lagom/serialization/Jsonable.html | 4 +- .../lagom/serialization/package-frame.html | 4 +- .../lagom/serialization/package-summary.html | 4 +- .../lagom/serialization/package-tree.html | 4 +- .../1.0.x/api/java/constant-values.html | 4 +- .../1.0.x/api/java/deprecated-list.html | 4 +- documentation/1.0.x/api/java/help-doc.html | 4 +- documentation/1.0.x/api/java/index-all.html | 320 ++++----------- documentation/1.0.x/api/java/index.html | 2 +- .../1.0.x/api/java/overview-frame.html | 4 +- .../1.0.x/api/java/overview-summary.html | 4 +- .../1.0.x/api/java/overview-tree.html | 27 +- .../1.0.x/api/java/serialized-form.html | 99 +---- documentation/1.0.x/api/java/stylesheet.css | 2 +- 251 files changed, 1165 insertions(+), 1283 deletions(-) create mode 100644 documentation/1.0.x/ReactivePlatform.html diff --git a/documentation/1.0.x/Cluster.html b/documentation/1.0.x/Cluster.html index c7231c97baa..02987bdf773 100644 --- a/documentation/1.0.x/Cluster.html +++ b/documentation/1.0.x/Cluster.html @@ -79,7 +79,7 @@

§Cluster

Alternatively, this can be defined as Java system properties when starting the JVM:

-Dakka.cluster.seed-nodes.0=akka.tcp://MyService@host1:2552
 -Dakka.cluster.seed-nodes.1=akka.tcp://MyService@host2:2552
-

The node that is configured first in the list of seed-nodes is special. Only that node that will join itself. It is used for bootstrapping the cluster.

The reason for the special first seed node is to avoid forming separated islands when starting from an empty cluster. If the first seed node is restarted and there is an existing cluster it will try to join the other seed nodes, i.e. it will join the existing cluster.

You can read more about cluster joining in the Akka documentation.

§Downing

When operating a Lagom service cluster you must consider how to handle network partitions (a.k.a. split brain scenarios) and machine crashes (including JVM and hardware failures). This is crucial for correct behavior when using Persistent Entities. Persistent entities must be single-writers, i.e. there must only be one active entity with a given entity identity. If the cluster is split in two halves and the wrong downing strategy is used there will be active entities with the the same identifiers in both clusters, writing to the same database. That will result in corrupt data.

The naïve approach is to remove an unreachable node from the cluster membership after a timeout. This works great for crashes and short transient network partitions, but not for long network partitions. Both sides of the network partition will see the other side as unreachable and after a while remove it from its cluster membership. Since this happens on both sides the result is that two separate disconnected clusters have been created. This approach is provided by the opt-in (off by default) auto-down feature in the OSS version of Akka Cluster.

We strongly recommend against using the auto-down feature of Akka Cluster.

A pre-packaged solution for the downing problem is provided by Split Brain Resolver, which is part of the Lightbend Reactive Platform. The keep-majority strategy is configured to be enabled by default if you use Lagom with the Reactive Platform.

If you don’t use RP, you should anyway carefully read the documentation of the Split Brain Resolver and make sure that the solution you are using handles the concerns described there.

§Leaving

When using Persistent Entities you can use PersistentEntityRegistry.gracefulShutdown to stop the persistent entities and leave the cluster in a graceful way. This is not mandatory but it can be good when you are doing a controlled shutdown of a service node. It will reduce the number of lost in-flight messages during the failover to another node.

§Dependency

The clustering feature is already included if you are using the persistence or pubsub modules.

If you want to enable it without those modules, add the following to your project’s build:

+

The node that is configured first in the list of seed-nodes is special. Only that node that will join itself. It is used for bootstrapping the cluster.

The reason for the special first seed node is to avoid forming separated islands when starting from an empty cluster. If the first seed node is restarted and there is an existing cluster it will try to join the other seed nodes, i.e. it will join the existing cluster.

You can read more about cluster joining in the Akka documentation.

§Downing

When operating a Lagom service cluster you must consider how to handle network partitions (a.k.a. split brain scenarios) and machine crashes (including JVM and hardware failures). This is crucial for correct behavior when using Persistent Entities. Persistent entities must be single-writers, i.e. there must only be one active entity with a given entity identity. If the cluster is split in two halves and the wrong downing strategy is used there will be active entities with the the same identifiers in both clusters, writing to the same database. That will result in corrupt data.

The naïve approach is to remove an unreachable node from the cluster membership after a timeout. This works great for crashes and short transient network partitions, but not for long network partitions. Both sides of the network partition will see the other side as unreachable and after a while remove it from its cluster membership. Since this happens on both sides the result is that two separate disconnected clusters have been created. This approach is provided by the opt-in (off by default) auto-down feature in the OSS version of Akka Cluster.

We strongly recommend against using the auto-down feature of Akka Cluster.

A pre-packaged solution for the downing problem is provided by Split Brain Resolver, which is part of the Lightbend Reactive Platform. The keep-majority strategy is configured to be enabled by default if you use Lagom with the Reactive Platform.

See Reactive Platform instructions for how to enable Reactive Platform in the build of your project.

If you don’t use RP, you should anyway carefully read the documentation of the Split Brain Resolver and make sure that the solution you are using handles the concerns described there.

§Leaving

When using Persistent Entities you can use PersistentEntityRegistry.gracefulShutdown to stop the persistent entities and leave the cluster in a graceful way. This is not mandatory but it can be good when you are doing a controlled shutdown of a service node. It will reduce the number of lost in-flight messages during the failover to another node.

§Dependency

The clustering feature is already included if you are using the persistence or pubsub modules.

If you want to enable it without those modules, add the following to your project’s build:

libraryDependencies += lagomJavadslCluster