9921 lines
1.7 MiB
9921 lines
1.7 MiB
<html><head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>Spring Cloud</title><link rel="stylesheet" type="text/css" href="css/manual-singlepage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>Spring Cloud</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#d0e9"></a></span></dt><dt><span class="chapter"><a href="#_features">1. Features</a></span></dt><dt><span class="part"><a href="#_cloud_native_applications">I. Cloud Native Applications</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_spring_cloud_context_application_context_services">2. Spring Cloud Context: Application Context Services</a></span></dt><dd><dl><dt><span class="section"><a href="#_the_bootstrap_application_context">2.1. The Bootstrap Application Context</a></span></dt><dt><span class="section"><a href="#_application_context_hierarchies">2.2. Application Context Hierarchies</a></span></dt><dt><span class="section"><a href="#customizing-bootstrap-properties">2.3. Changing the Location of Bootstrap Properties</a></span></dt><dt><span class="section"><a href="#overriding-bootstrap-properties">2.4. Overriding the Values of Remote Properties</a></span></dt><dt><span class="section"><a href="#_customizing_the_bootstrap_configuration">2.5. Customizing the Bootstrap Configuration</a></span></dt><dt><span class="section"><a href="#customizing-bootstrap-property-sources">2.6. Customizing the Bootstrap Property Sources</a></span></dt><dt><span class="section"><a href="#_environment_changes">2.7. Environment Changes</a></span></dt><dt><span class="section"><a href="#_refresh_scope">2.8. Refresh Scope</a></span></dt><dt><span class="section"><a href="#_encryption_and_decryption">2.9. Encryption and Decryption</a></span></dt><dt><span class="section"><a href="#_endpoints">2.10. Endpoints</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_spring_cloud_commons_common_abstractions">3. Spring Cloud Commons: Common Abstractions</a></span></dt><dd><dl><dt><span class="section"><a href="#__enablediscoveryclient">3.1. @EnableDiscoveryClient</a></span></dt><dt><span class="section"><a href="#_serviceregistry">3.2. ServiceRegistry</a></span></dt><dd><dl><dt><span class="section"><a href="#_serviceregistry_auto_registration">3.2.1. ServiceRegistry Auto-Registration</a></span></dt><dt><span class="section"><a href="#_service_registry_actuator_endpoint">3.2.2. Service Registry Actuator Endpoint</a></span></dt></dl></dd><dt><span class="section"><a href="#_spring_resttemplate_as_a_load_balancer_client">3.3. Spring RestTemplate as a Load Balancer Client</a></span></dt><dd><dl><dt><span class="section"><a href="#_retrying_failed_requests">3.3.1. Retrying Failed Requests</a></span></dt></dl></dd><dt><span class="section"><a href="#_multiple_resttemplate_objects">3.4. Multiple RestTemplate objects</a></span></dt><dt><span class="section"><a href="#ignore-network-interfaces">3.5. Ignore Network Interfaces</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#_spring_cloud_config">II. Spring Cloud Config</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_quick_start">4. Quick Start</a></span></dt><dd><dl><dt><span class="section"><a href="#_client_side_usage">4.1. Client Side Usage</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_spring_cloud_config_server">5. Spring Cloud Config Server</a></span></dt><dd><dl><dt><span class="section"><a href="#_environment_repository">5.1. Environment Repository</a></span></dt><dd><dl><dt><span class="section"><a href="#_git_backend">5.1.1. Git Backend</a></span></dt><dd><dl><dt><span class="section"><a href="#_placeholders_in_git_uri">Placeholders in Git URI</a></span></dt><dt><span class="section"><a href="#_pattern_matching_and_multiple_repositories">Pattern Matching and Multiple Repositories</a></span></dt><dt><span class="section"><a href="#_authentication">Authentication</a></span></dt><dt><span class="section"><a href="#_authentication_with_aws_codecommit">Authentication with AWS CodeCommit</a></span></dt><dt><span class="section"><a href="#_git_ssh_configuration_using_properties">Git SSH configuration using properties</a></span></dt><dt><span class="section"><a href="#_placeholders_in_git_search_paths">Placeholders in Git Search Paths</a></span></dt><dt><span class="section"><a href="#_force_pull_in_git_repositories">Force pull in Git Repositories</a></span></dt></dl></dd><dt><span class="section"><a href="#_version_control_backend_filesystem_use">5.1.2. Version Control Backend Filesystem Use</a></span></dt><dt><span class="section"><a href="#_file_system_backend">5.1.3. File System Backend</a></span></dt><dt><span class="section"><a href="#_vault_backend">5.1.4. Vault Backend</a></span></dt><dd><dl><dt><span class="section"><a href="#_multiple_properties_sources">Multiple Properties Sources</a></span></dt></dl></dd><dt><span class="section"><a href="#_sharing_configuration_with_all_applications">5.1.5. Sharing Configuration With All Applications</a></span></dt><dd><dl><dt><span class="section"><a href="#_file_based_repositories">File Based Repositories</a></span></dt><dt><span class="section"><a href="#_vault_server">Vault Server</a></span></dt></dl></dd><dt><span class="section"><a href="#_composite_environment_repositories">5.1.6. Composite Environment Repositories</a></span></dt><dd><dl><dt><span class="section"><a href="#_custom_composite_environment_repositories">Custom Composite Environment Repositories</a></span></dt></dl></dd><dt><span class="section"><a href="#_property_overrides">5.1.7. Property Overrides</a></span></dt></dl></dd><dt><span class="section"><a href="#_health_indicator">5.2. Health Indicator</a></span></dt><dt><span class="section"><a href="#_security">5.3. Security</a></span></dt><dt><span class="section"><a href="#_encryption_and_decryption_2">5.4. Encryption and Decryption</a></span></dt><dt><span class="section"><a href="#_key_management">5.5. Key Management</a></span></dt><dt><span class="section"><a href="#_creating_a_key_store_for_testing">5.6. Creating a Key Store for Testing</a></span></dt><dt><span class="section"><a href="#_using_multiple_keys_and_key_rotation">5.7. Using Multiple Keys and Key Rotation</a></span></dt><dt><span class="section"><a href="#_serving_encrypted_properties">5.8. Serving Encrypted Properties</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_serving_alternative_formats">6. Serving Alternative Formats</a></span></dt><dt><span class="chapter"><a href="#_serving_plain_text">7. Serving Plain Text</a></span></dt><dt><span class="chapter"><a href="#_embedding_the_config_server">8. Embedding the Config Server</a></span></dt><dt><span class="chapter"><a href="#_push_notifications_and_spring_cloud_bus">9. Push Notifications and Spring Cloud Bus</a></span></dt><dt><span class="chapter"><a href="#_spring_cloud_config_client">10. Spring Cloud Config Client</a></span></dt><dd><dl><dt><span class="section"><a href="#config-first-bootstrap">10.1. Config First Bootstrap</a></span></dt><dt><span class="section"><a href="#discovery-first-bootstrap">10.2. Discovery First Bootstrap</a></span></dt><dt><span class="section"><a href="#config-client-fail-fast">10.3. Config Client Fail Fast</a></span></dt><dt><span class="section"><a href="#config-client-retry">10.4. Config Client Retry</a></span></dt><dt><span class="section"><a href="#_locating_remote_configuration_resources">10.5. Locating Remote Configuration Resources</a></span></dt><dt><span class="section"><a href="#_security_2">10.6. Security</a></span></dt><dd><dl><dt><span class="section"><a href="#_health_indicator_2">10.6.1. Health Indicator</a></span></dt><dt><span class="section"><a href="#custom-rest-template">10.6.2. Providing A Custom RestTemplate</a></span></dt><dt><span class="section"><a href="#_vault">10.6.3. Vault</a></span></dt></dl></dd><dt><span class="section"><a href="#_vault_2">10.7. Vault</a></span></dt><dd><dl><dt><span class="section"><a href="#_nested_keys_in_vault">10.7.1. Nested Keys In Vault</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="part"><a href="#_spring_cloud_netflix">III. Spring Cloud Netflix</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_service_discovery_eureka_clients">11. Service Discovery: Eureka Clients</a></span></dt><dd><dl><dt><span class="section"><a href="#netflix-eureka-client-starter">11.1. How to Include Eureka Client</a></span></dt><dt><span class="section"><a href="#_registering_with_eureka">11.2. Registering with Eureka</a></span></dt><dt><span class="section"><a href="#_authenticating_with_the_eureka_server">11.3. Authenticating with the Eureka Server</a></span></dt><dt><span class="section"><a href="#_status_page_and_health_indicator">11.4. Status Page and Health Indicator</a></span></dt><dt><span class="section"><a href="#_registering_a_secure_application">11.5. Registering a Secure Application</a></span></dt><dt><span class="section"><a href="#_eureka_s_health_checks">11.6. Eureka’s Health Checks</a></span></dt><dt><span class="section"><a href="#_eureka_metadata_for_instances_and_clients">11.7. Eureka Metadata for Instances and Clients</a></span></dt><dd><dl><dt><span class="section"><a href="#_using_eureka_on_cloudfoundry">11.7.1. Using Eureka on Cloudfoundry</a></span></dt><dt><span class="section"><a href="#_using_eureka_on_aws">11.7.2. Using Eureka on AWS</a></span></dt><dt><span class="section"><a href="#_changing_the_eureka_instance_id">11.7.3. Changing the Eureka Instance ID</a></span></dt></dl></dd><dt><span class="section"><a href="#_using_the_eurekaclient">11.8. Using the EurekaClient</a></span></dt><dt><span class="section"><a href="#_alternatives_to_the_native_netflix_eurekaclient">11.9. Alternatives to the native Netflix EurekaClient</a></span></dt><dt><span class="section"><a href="#_why_is_it_so_slow_to_register_a_service">11.10. Why is it so Slow to Register a Service?</a></span></dt><dt><span class="section"><a href="#_zones">11.11. Zones</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-eureka-server">12. Service Discovery: Eureka Server</a></span></dt><dd><dl><dt><span class="section"><a href="#netflix-eureka-server-starter">12.1. How to Include Eureka Server</a></span></dt><dt><span class="section"><a href="#spring-cloud-running-eureka-server">12.2. How to Run a Eureka Server</a></span></dt><dt><span class="section"><a href="#spring-cloud-eureka-server-zones-and-regions">12.3. High Availability, Zones and Regions</a></span></dt><dt><span class="section"><a href="#_standalone_mode">12.4. Standalone Mode</a></span></dt><dt><span class="section"><a href="#_peer_awareness">12.5. Peer Awareness</a></span></dt><dt><span class="section"><a href="#_prefer_ip_address">12.6. Prefer IP Address</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_circuit_breaker_hystrix_clients">13. Circuit Breaker: Hystrix Clients</a></span></dt><dd><dl><dt><span class="section"><a href="#netflix-hystrix-starter">13.1. How to Include Hystrix</a></span></dt><dt><span class="section"><a href="#_propagating_the_security_context_or_using_spring_scopes">13.2. Propagating the Security Context or using Spring Scopes</a></span></dt><dt><span class="section"><a href="#_health_indicator_3">13.3. Health Indicator</a></span></dt><dt><span class="section"><a href="#_hystrix_metrics_stream">13.4. Hystrix Metrics Stream</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_circuit_breaker_hystrix_dashboard">14. Circuit Breaker: Hystrix Dashboard</a></span></dt><dt><span class="chapter"><a href="#_hystrix_timeouts_and_ribbon_clients">15. Hystrix Timeouts And Ribbon Clients</a></span></dt><dd><dl><dt><span class="section"><a href="#netflix-hystrix-dashboard-starter">15.1. How to Include Hystrix Dashboard</a></span></dt><dt><span class="section"><a href="#_turbine">15.2. Turbine</a></span></dt><dt><span class="section"><a href="#_turbine_stream">15.3. Turbine Stream</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-ribbon">16. Client Side Load Balancer: Ribbon</a></span></dt><dd><dl><dt><span class="section"><a href="#netflix-ribbon-starter">16.1. How to Include Ribbon</a></span></dt><dt><span class="section"><a href="#_customizing_the_ribbon_client">16.2. Customizing the Ribbon Client</a></span></dt><dt><span class="section"><a href="#_customizing_the_ribbon_client_using_properties">16.3. Customizing the Ribbon Client using properties</a></span></dt><dt><span class="section"><a href="#_using_ribbon_with_eureka">16.4. Using Ribbon with Eureka</a></span></dt><dt><span class="section"><a href="#spring-cloud-ribbon-without-eureka">16.5. Example: How to Use Ribbon Without Eureka</a></span></dt><dt><span class="section"><a href="#_example_disable_eureka_use_in_ribbon">16.6. Example: Disable Eureka use in Ribbon</a></span></dt><dt><span class="section"><a href="#_using_the_ribbon_api_directly">16.7. Using the Ribbon API Directly</a></span></dt><dt><span class="section"><a href="#ribbon-child-context-eager-load">16.8. Caching of Ribbon Configuration</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-feign">17. Declarative REST Client: Feign</a></span></dt><dd><dl><dt><span class="section"><a href="#netflix-feign-starter">17.1. How to Include Feign</a></span></dt><dt><span class="section"><a href="#spring-cloud-feign-overriding-defaults">17.2. Overriding Feign Defaults</a></span></dt><dt><span class="section"><a href="#_creating_feign_clients_manually">17.3. Creating Feign Clients Manually</a></span></dt><dt><span class="section"><a href="#spring-cloud-feign-hystrix">17.4. Feign Hystrix Support</a></span></dt><dt><span class="section"><a href="#spring-cloud-feign-hystrix-fallback">17.5. Feign Hystrix Fallbacks</a></span></dt><dt><span class="section"><a href="#_feign_and_literal_primary_literal">17.6. Feign and <code class="literal">@Primary</code></a></span></dt><dt><span class="section"><a href="#spring-cloud-feign-inheritance">17.7. Feign Inheritance Support</a></span></dt><dt><span class="section"><a href="#_feign_request_response_compression">17.8. Feign request/response compression</a></span></dt><dt><span class="section"><a href="#_feign_logging">17.9. Feign logging</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_external_configuration_archaius">18. External Configuration: Archaius</a></span></dt><dt><span class="chapter"><a href="#_router_and_filter_zuul">19. Router and Filter: Zuul</a></span></dt><dd><dl><dt><span class="section"><a href="#netflix-zuul-starter">19.1. How to Include Zuul</a></span></dt><dt><span class="section"><a href="#netflix-zuul-reverse-proxy">19.2. Embedded Zuul Reverse Proxy</a></span></dt><dt><span class="section"><a href="#_zuul_http_client">19.3. Zuul Http Client</a></span></dt><dt><span class="section"><a href="#_cookies_and_sensitive_headers">19.4. Cookies and Sensitive Headers</a></span></dt><dt><span class="section"><a href="#_ignored_headers">19.5. Ignored Headers</a></span></dt><dt><span class="section"><a href="#_the_routes_endpoint">19.6. The Routes Endpoint</a></span></dt><dt><span class="section"><a href="#_strangulation_patterns_and_local_forwards">19.7. Strangulation Patterns and Local Forwards</a></span></dt><dt><span class="section"><a href="#_uploading_files_through_zuul">19.8. Uploading Files through Zuul</a></span></dt><dt><span class="section"><a href="#_query_string_encoding">19.9. Query String Encoding</a></span></dt><dt><span class="section"><a href="#_plain_embedded_zuul">19.10. Plain Embedded Zuul</a></span></dt><dt><span class="section"><a href="#_disable_zuul_filters">19.11. Disable Zuul Filters</a></span></dt><dt><span class="section"><a href="#hystrix-fallbacks-for-routes">19.12. Providing Hystrix Fallbacks For Routes</a></span></dt><dt><span class="section"><a href="#zuul-developer-guide">19.13. Zuul Developer Guide</a></span></dt><dd><dl><dt><span class="section"><a href="#_the_zuul_servlet">19.13.1. The Zuul Servlet</a></span></dt><dt><span class="section"><a href="#_zuul_requestcontext">19.13.2. Zuul RequestContext</a></span></dt><dt><span class="section"><a href="#__literal_enablezuulproxy_literal_vs_literal_enablezuulserver_literal">19.13.3. <code class="literal">@EnableZuulProxy</code> vs. <code class="literal">@EnableZuulServer</code></a></span></dt><dt><span class="section"><a href="#__literal_enablezuulserver_literal_filters">19.13.4. <code class="literal">@EnableZuulServer</code> Filters</a></span></dt><dt><span class="section"><a href="#__literal_enablezuulproxy_literal_filters">19.13.5. <code class="literal">@EnableZuulProxy</code> Filters</a></span></dt><dt><span class="section"><a href="#_custom_zuul_filter_examples">19.13.6. Custom Zuul Filter examples</a></span></dt><dt><span class="section"><a href="#_how_to_write_a_pre_filter">19.13.7. How to Write a Pre Filter</a></span></dt><dt><span class="section"><a href="#_how_to_write_a_route_filter">19.13.8. How to Write a Route Filter</a></span></dt><dt><span class="section"><a href="#_how_to_write_a_post_filter">19.13.9. How to Write a Post Filter</a></span></dt><dt><span class="section"><a href="#_how_zuul_errors_work">19.13.10. How Zuul Errors Work</a></span></dt><dt><span class="section"><a href="#_zuul_eager_application_context_loading">19.13.11. Zuul Eager Application Context Loading</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_polyglot_support_with_sidecar">20. Polyglot support with Sidecar</a></span></dt><dt><span class="chapter"><a href="#netflix-rxjava-springmvc">21. RxJava with Spring MVC</a></span></dt><dt><span class="chapter"><a href="#netflix-metrics">22. Metrics: Spectator, Servo, and Atlas</a></span></dt><dd><dl><dt><span class="section"><a href="#_dimensional_vs_hierarchical_metrics">22.1. Dimensional vs. Hierarchical Metrics</a></span></dt><dt><span class="section"><a href="#_default_metrics_collection">22.2. Default Metrics Collection</a></span></dt><dt><span class="section"><a href="#netflix-metrics-spectator">22.3. Metrics Collection: Spectator</a></span></dt><dd><dl><dt><span class="section"><a href="#_spectator_counter">22.3.1. Spectator Counter</a></span></dt><dt><span class="section"><a href="#_spectator_timer">22.3.2. Spectator Timer</a></span></dt><dt><span class="section"><a href="#_spectator_gauge">22.3.3. Spectator Gauge</a></span></dt><dt><span class="section"><a href="#_spectator_distribution_summaries">22.3.4. Spectator Distribution Summaries</a></span></dt></dl></dd><dt><span class="section"><a href="#netflix-metrics-servo">22.4. Metrics Collection: Servo</a></span></dt><dd><dl><dt><span class="section"><a href="#_creating_servo_monitors">22.4.1. Creating Servo Monitors</a></span></dt></dl></dd><dt><span class="section"><a href="#netflix-metrics-atlas">22.5. Metrics Backend: Atlas</a></span></dt><dd><dl><dt><span class="section"><a href="#_global_tags">22.5.1. Global tags</a></span></dt><dt><span class="section"><a href="#_using_atlas">22.5.2. Using Atlas</a></span></dt></dl></dd><dt><span class="section"><a href="#retrying-failed-requests">22.6. Retrying Failed Requests</a></span></dt><dd><dl><dt><span class="section"><a href="#_configuration">22.6.1. Configuration</a></span></dt><dt><span class="section"><a href="#_zuul">22.6.2. Zuul</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="part"><a href="#_spring_cloud_stream">IV. Spring Cloud Stream</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_introducing_spring_cloud_stream">23. Introducing Spring Cloud Stream</a></span></dt><dt><span class="chapter"><a href="#_main_concepts">24. Main Concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#_application_model">24.1. Application Model</a></span></dt><dd><dl><dt><span class="section"><a href="#_fat_jar">24.1.1. Fat JAR</a></span></dt></dl></dd><dt><span class="section"><a href="#_the_binder_abstraction">24.2. The Binder Abstraction</a></span></dt><dt><span class="section"><a href="#_persistent_publish_subscribe_support">24.3. Persistent Publish-Subscribe Support</a></span></dt><dt><span class="section"><a href="#consumer-groups">24.4. Consumer Groups</a></span></dt><dd><dl><dt><span class="section"><a href="#durability">24.4.1. Durability</a></span></dt></dl></dd><dt><span class="section"><a href="#partitioning">24.5. Partitioning Support</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_programming_model">25. Programming Model</a></span></dt><dd><dl><dt><span class="section"><a href="#_declaring_and_binding_channels">25.1. Declaring and Binding Channels</a></span></dt><dd><dl><dt><span class="section"><a href="#_triggering_binding_via_literal_enablebinding_literal">25.1.1. Triggering Binding Via <code class="literal">@EnableBinding</code></a></span></dt><dt><span class="section"><a href="#__literal_input_literal_and_literal_output_literal">25.1.2. <code class="literal">@Input</code> and <code class="literal">@Output</code></a></span></dt><dd><dl><dt><span class="section"><a href="#_customizing_channel_names">Customizing Channel Names</a></span></dt><dt><span class="section"><a href="#__literal_source_literal_literal_sink_literal_and_literal_processor_literal"><code class="literal">Source</code>, <code class="literal">Sink</code>, and <code class="literal">Processor</code></a></span></dt></dl></dd><dt><span class="section"><a href="#_accessing_bound_channels">25.1.3. Accessing Bound Channels</a></span></dt><dd><dl><dt><span class="section"><a href="#_injecting_the_bound_interfaces">Injecting the Bound Interfaces</a></span></dt><dt><span class="section"><a href="#_injecting_channels_directly">Injecting Channels Directly</a></span></dt></dl></dd><dt><span class="section"><a href="#_producing_and_consuming_messages">25.1.4. Producing and Consuming Messages</a></span></dt><dd><dl><dt><span class="section"><a href="#_native_spring_integration_support">Native Spring Integration Support</a></span></dt><dt><span class="section"><a href="#_spring_integration_error_channel_support">Spring Integration Error Channel Support</a></span></dt><dt><span class="section"><a href="#_using_streamlistener_for_automatic_content_type_handling">Using @StreamListener for Automatic Content Type Handling</a></span></dt><dt><span class="section"><a href="#_using_streamlistener_for_dispatching_messages_to_multiple_methods">Using @StreamListener for dispatching messages to multiple methods</a></span></dt></dl></dd><dt><span class="section"><a href="#_reactive_programming_support">25.1.5. Reactive Programming Support</a></span></dt><dd><dl><dt><span class="section"><a href="#_reactor_based_handlers">Reactor-based handlers</a></span></dt><dt><span class="section"><a href="#_rxjava_1_x_support">RxJava 1.x support</a></span></dt></dl></dd><dt><span class="section"><a href="#_aggregation">25.1.6. Aggregation</a></span></dt><dd><dl><dt><span class="section"><a href="#_configuring_aggregate_application">Configuring aggregate application</a></span></dt><dt><span class="section"><a href="#_configuring_binding_service_properties_for_non_self_contained_aggregate_application">Configuring binding service properties for non self contained aggregate application</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="chapter"><a href="#_binders">26. Binders</a></span></dt><dd><dl><dt><span class="section"><a href="#_producers_and_consumers">26.1. Producers and Consumers</a></span></dt><dt><span class="section"><a href="#_binder_spi">26.2. Binder SPI</a></span></dt><dt><span class="section"><a href="#_binder_detection">26.3. Binder Detection</a></span></dt><dd><dl><dt><span class="section"><a href="#_classpath_detection">26.3.1. Classpath Detection</a></span></dt></dl></dd><dt><span class="section"><a href="#multiple-binders">26.4. Multiple Binders on the Classpath</a></span></dt><dt><span class="section"><a href="#multiple-systems">26.5. Connecting to Multiple Systems</a></span></dt><dt><span class="section"><a href="#_binder_configuration_properties">26.6. Binder configuration properties</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_configuration_options">27. Configuration Options</a></span></dt><dd><dl><dt><span class="section"><a href="#_spring_cloud_stream_properties">27.1. Spring Cloud Stream Properties</a></span></dt><dt><span class="section"><a href="#binding-properties">27.2. Binding Properties</a></span></dt><dd><dl><dt><span class="section"><a href="#_properties_for_use_of_spring_cloud_stream">27.2.1. Properties for Use of Spring Cloud Stream</a></span></dt><dt><span class="section"><a href="#_consumer_properties">27.2.2. Consumer properties</a></span></dt><dt><span class="section"><a href="#_producer_properties">27.2.3. Producer Properties</a></span></dt></dl></dd><dt><span class="section"><a href="#dynamicdestination">27.3. Using dynamically bound destinations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#contenttypemanagement">28. Content Type and Transformation</a></span></dt><dd><dl><dt><span class="section"><a href="#mime-types">28.1. MIME types</a></span></dt><dt><span class="section"><a href="#mime-types-and-java-types">28.2. MIME types and Java types</a></span></dt><dt><span class="section"><a href="#_customizing_message_conversion">28.3. Customizing message conversion</a></span></dt><dt><span class="section"><a href="#__literal_streamlistener_literal_and_message_conversion">28.4. <code class="literal">@StreamListener</code> and Message Conversion</a></span></dt></dl></dd><dt><span class="chapter"><a href="#schema-evolution">29. Schema evolution support</a></span></dt><dd><dl><dt><span class="section"><a href="#_apache_avro_message_converters">29.1. Apache Avro Message Converters</a></span></dt><dt><span class="section"><a href="#_converters_with_schema_support">29.2. Converters with schema support</a></span></dt><dt><span class="section"><a href="#_schema_registry_support">29.3. Schema Registry Support</a></span></dt><dt><span class="section"><a href="#_schema_registry_server">29.4. Schema Registry Server</a></span></dt><dd><dl><dt><span class="section"><a href="#_schema_registry_server_api">29.4.1. Schema Registry Server API</a></span></dt><dd><dl><dt><span class="section"><a href="#__literal_post_literal"><code class="literal">POST /</code></a></span></dt><dt><span class="section"><a href="#__literal_get_subject_format_version_literal"><code class="literal">GET /{subject}/{format}/{version}</code></a></span></dt><dt><span class="section"><a href="#__literal_get_subject_format_literal"><code class="literal">GET /{subject}/{format}</code></a></span></dt><dt><span class="section"><a href="#__literal_get_schemas_id_literal"><code class="literal">GET /schemas/{id}</code></a></span></dt><dt><span class="section"><a href="#__literal_delete_subject_format_version_literal"><code class="literal">DELETE /{subject}/{format}/{version}</code></a></span></dt><dt><span class="section"><a href="#__literal_delete_schemas_id_literal"><code class="literal">DELETE /schemas/{id}</code></a></span></dt><dt><span class="section"><a href="#__literal_delete_subject_literal"><code class="literal">DELETE /{subject}</code></a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_schema_registry_client">29.5. Schema Registry Client</a></span></dt><dd><dl><dt><span class="section"><a href="#_schema_registry_client_properties">29.5.1. Schema Registry Client properties</a></span></dt></dl></dd><dt><span class="section"><a href="#_avro_schema_registry_client_message_converters">29.6. Avro Schema Registry Client Message Converters</a></span></dt><dd><dl><dt><span class="section"><a href="#_avro_schema_registry_message_converter_properties">29.6.1. Avro Schema Registry Message Converter properties</a></span></dt></dl></dd><dt><span class="section"><a href="#_schema_registration_and_resolution">29.7. Schema Registration and Resolution</a></span></dt><dd><dl><dt><span class="section"><a href="#_schema_registration_process_serialization">29.7.1. Schema Registration Process (Serialization)</a></span></dt><dt><span class="section"><a href="#_schema_resolution_process_deserialization">29.7.2. Schema Resolution Process (Deserialization)</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_inter_application_communication">30. Inter-Application Communication</a></span></dt><dd><dl><dt><span class="section"><a href="#_connecting_multiple_application_instances">30.1. Connecting Multiple Application Instances</a></span></dt><dt><span class="section"><a href="#_instance_index_and_instance_count">30.2. Instance Index and Instance Count</a></span></dt><dt><span class="section"><a href="#_partitioning">30.3. Partitioning</a></span></dt><dd><dl><dt><span class="section"><a href="#_configuring_output_bindings_for_partitioning">30.3.1. Configuring Output Bindings for Partitioning</a></span></dt><dd><dl><dt><span class="section"><a href="#_spring_managed_custom_literal_partitionkeyextractorclass_literal_implementations">Spring-managed custom <code class="literal">PartitionKeyExtractorClass</code> implementations</a></span></dt><dt><span class="section"><a href="#_configuring_input_bindings_for_partitioning">Configuring Input Bindings for Partitioning</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="chapter"><a href="#_testing">31. Testing</a></span></dt><dt><span class="chapter"><a href="#_health_indicator_4">32. Health Indicator</a></span></dt><dt><span class="chapter"><a href="#_metrics_emitter">33. Metrics Emitter</a></span></dt><dt><span class="chapter"><a href="#_samples">34. Samples</a></span></dt><dt><span class="chapter"><a href="#_getting_started">35. Getting Started</a></span></dt></dl></dd><dt><span class="part"><a href="#_binder_implementations">V. Binder Implementations</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_apache_kafka_binder">36. Apache Kafka Binder</a></span></dt><dd><dl><dt><span class="section"><a href="#_usage">36.1. Usage</a></span></dt><dt><span class="section"><a href="#_apache_kafka_binder_overview">36.2. Apache Kafka Binder Overview</a></span></dt><dt><span class="section"><a href="#_configuration_options_2">36.3. Configuration Options</a></span></dt><dd><dl><dt><span class="section"><a href="#_kafka_binder_properties">36.3.1. Kafka Binder Properties</a></span></dt><dt><span class="section"><a href="#_kafka_consumer_properties">36.3.2. Kafka Consumer Properties</a></span></dt><dt><span class="section"><a href="#_kafka_producer_properties">36.3.3. Kafka Producer Properties</a></span></dt><dt><span class="section"><a href="#_usage_examples">36.3.4. Usage examples</a></span></dt><dd><dl><dt><span class="section"><a href="#_example_setting_literal_autocommitoffset_literal_false_and_relying_on_manual_acking">Example: Setting <code class="literal">autoCommitOffset</code> false and relying on manual acking.</a></span></dt><dt><span class="section"><a href="#_example_security_configuration">Example: security configuration</a></span></dt><dt><span class="section"><a href="#_using_the_binder_with_apache_kafka_0_10">Using the binder with Apache Kafka 0.10</a></span></dt><dt><span class="section"><a href="#exclude-admin-utils">Excluding Kafka broker jar from the classpath of the binder based application</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#kafka-dlq-processing">36.4. Dead-Letter Topic Processing</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_rabbitmq_binder">37. RabbitMQ Binder</a></span></dt><dd><dl><dt><span class="section"><a href="#_usage_2">37.1. Usage</a></span></dt><dt><span class="section"><a href="#_rabbitmq_binder_overview">37.2. RabbitMQ Binder Overview</a></span></dt><dt><span class="section"><a href="#_configuration_options_3">37.3. Configuration Options</a></span></dt><dd><dl><dt><span class="section"><a href="#rabbit-binder-properties">37.3.1. RabbitMQ Binder Properties</a></span></dt><dt><span class="section"><a href="#_rabbitmq_consumer_properties">37.3.2. RabbitMQ Consumer Properties</a></span></dt><dt><span class="section"><a href="#_rabbit_producer_properties">37.3.3. Rabbit Producer Properties</a></span></dt></dl></dd><dt><span class="section"><a href="#_retry_with_the_rabbitmq_binder">37.4. Retry With the RabbitMQ Binder</a></span></dt><dd><dl><dt><span class="section"><a href="#_overview">37.4.1. Overview</a></span></dt><dt><span class="section"><a href="#_putting_it_all_together">37.4.2. Putting it All Together</a></span></dt></dl></dd><dt><span class="section"><a href="#rabbit-dlq-processing">37.5. Dead-Letter Queue Processing</a></span></dt><dd><dl><dt><span class="section"><a href="#_non_partitioned_destinations">37.5.1. Non-Partitioned Destinations</a></span></dt><dt><span class="section"><a href="#_partitioned_destinations">37.5.2. Partitioned Destinations</a></span></dt><dd><dl><dt><span class="section"><a href="#_republishtodlq_false">republishToDlq=false</a></span></dt><dt><span class="section"><a href="#_republishtodlq_true">republishToDlq=true</a></span></dt></dl></dd></dl></dd></dl></dd></dl></dd><dt><span class="part"><a href="#_spring_cloud_bus">VI. Spring Cloud Bus</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_quick_start_2">38. Quick Start</a></span></dt><dt><span class="chapter"><a href="#_addressing_an_instance">39. Addressing an Instance</a></span></dt><dt><span class="chapter"><a href="#_addressing_all_instances_of_a_service">40. Addressing all instances of a service</a></span></dt><dt><span class="chapter"><a href="#_application_context_id_must_be_unique">41. Application Context ID must be unique</a></span></dt><dt><span class="chapter"><a href="#_customizing_the_message_broker">42. Customizing the Message Broker</a></span></dt><dt><span class="chapter"><a href="#_tracing_bus_events">43. Tracing Bus Events</a></span></dt><dt><span class="chapter"><a href="#_broadcasting_your_own_events">44. Broadcasting Your Own Events</a></span></dt><dd><dl><dt><span class="section"><a href="#_registering_events_in_custom_packages">44.1. Registering events in custom packages</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#_spring_cloud_sleuth">VII. Spring Cloud Sleuth</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_introduction">45. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#_terminology">45.1. Terminology</a></span></dt><dt><span class="section"><a href="#_purpose">45.2. Purpose</a></span></dt><dd><dl><dt><span class="section"><a href="#_distributed_tracing_with_zipkin">45.2.1. Distributed tracing with Zipkin</a></span></dt><dt><span class="section"><a href="#_visualizing_errors">45.2.2. Visualizing errors</a></span></dt><dt><span class="section"><a href="#_live_examples">45.2.3. Live examples</a></span></dt><dt><span class="section"><a href="#_log_correlation">45.2.4. Log correlation</a></span></dt><dd><dl><dt><span class="section"><a href="#_json_logback_with_logstash">JSON Logback with Logstash</a></span></dt></dl></dd><dt><span class="section"><a href="#_propagating_span_context">45.2.5. Propagating Span Context</a></span></dt><dd><dl><dt><span class="section"><a href="#_baggage_vs_span_tags">Baggage vs. Span Tags</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_adding_to_the_project">45.3. Adding to the project</a></span></dt><dd><dl><dt><span class="section"><a href="#_only_sleuth_log_correlation">45.3.1. Only Sleuth (log correlation)</a></span></dt><dt><span class="section"><a href="#_sleuth_with_zipkin_via_http">45.3.2. Sleuth with Zipkin via HTTP</a></span></dt><dt><span class="section"><a href="#_sleuth_with_zipkin_via_spring_cloud_stream">45.3.3. Sleuth with Zipkin via Spring Cloud Stream</a></span></dt><dt><span class="section"><a href="#_spring_cloud_sleuth_stream_zipkin_collector">45.3.4. Spring Cloud Sleuth Stream Zipkin Collector</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_additional_resources">46. Additional resources</a></span></dt><dt><span class="chapter"><a href="#_features_2">47. Features</a></span></dt><dt><span class="chapter"><a href="#_sampling">48. Sampling</a></span></dt><dt><span class="chapter"><a href="#_instrumentation">49. Instrumentation</a></span></dt><dt><span class="chapter"><a href="#_span_lifecycle">50. Span lifecycle</a></span></dt><dd><dl><dt><span class="section"><a href="#creating-and-closing-spans">50.1. Creating and closing spans</a></span></dt><dt><span class="section"><a href="#continuing-spans">50.2. Continuing spans</a></span></dt><dt><span class="section"><a href="#creating-spans-with-explicit-parent">50.3. Creating spans with an explicit parent</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_naming_spans">51. Naming spans</a></span></dt><dd><dl><dt><span class="section"><a href="#__spanname_annotation">51.1. @SpanName annotation</a></span></dt><dt><span class="section"><a href="#_tostring_method">51.2. toString() method</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_managing_spans_with_annotations">52. Managing spans with annotations</a></span></dt><dd><dl><dt><span class="section"><a href="#_rationale">52.1. Rationale</a></span></dt><dt><span class="section"><a href="#_creating_new_spans">52.2. Creating new spans</a></span></dt><dt><span class="section"><a href="#_continuing_spans">52.3. Continuing spans</a></span></dt><dt><span class="section"><a href="#_more_advanced_tag_setting">52.4. More advanced tag setting</a></span></dt><dd><dl><dt><span class="section"><a href="#_custom_extractor">52.4.1. Custom extractor</a></span></dt><dt><span class="section"><a href="#_resolving_expressions_for_value">52.4.2. Resolving expressions for value</a></span></dt><dt><span class="section"><a href="#_using_tostring_method">52.4.3. Using toString method</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_customizations">53. Customizations</a></span></dt><dd><dl><dt><span class="section"><a href="#_spring_integration">53.1. Spring Integration</a></span></dt><dt><span class="section"><a href="#_http">53.2. HTTP</a></span></dt><dt><span class="section"><a href="#_example">53.3. Example</a></span></dt><dt><span class="section"><a href="#_tracefilter">53.4. TraceFilter</a></span></dt><dt><span class="section"><a href="#_custom_sa_tag_in_zipkin">53.5. Custom SA tag in Zipkin</a></span></dt><dt><span class="section"><a href="#_custom_service_name">53.6. Custom service name</a></span></dt><dt><span class="section"><a href="#_customization_of_reported_spans">53.7. Customization of reported spans</a></span></dt><dt><span class="section"><a href="#_host_locator">53.8. Host locator</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_span_data_as_messages">54. Span Data as Messages</a></span></dt><dd><dl><dt><span class="section"><a href="#_zipkin_consumer">54.1. Zipkin Consumer</a></span></dt><dt><span class="section"><a href="#_custom_consumer">54.2. Custom Consumer</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_metrics">55. Metrics</a></span></dt><dt><span class="chapter"><a href="#_integrations">56. Integrations</a></span></dt><dd><dl><dt><span class="section"><a href="#_runnable_and_callable">56.1. Runnable and Callable</a></span></dt><dt><span class="section"><a href="#_hystrix">56.2. Hystrix</a></span></dt><dd><dl><dt><span class="section"><a href="#_custom_concurrency_strategy">56.2.1. Custom Concurrency Strategy</a></span></dt><dt><span class="section"><a href="#_manual_command_setting">56.2.2. Manual Command setting</a></span></dt></dl></dd><dt><span class="section"><a href="#_rxjava">56.3. RxJava</a></span></dt><dt><span class="section"><a href="#_http_integration">56.4. HTTP integration</a></span></dt><dd><dl><dt><span class="section"><a href="#_http_filter">56.4.1. HTTP Filter</a></span></dt><dt><span class="section"><a href="#_handlerinterceptor">56.4.2. HandlerInterceptor</a></span></dt><dt><span class="section"><a href="#_async_servlet_support">56.4.3. Async Servlet support</a></span></dt></dl></dd><dt><span class="section"><a href="#_http_client_integration">56.5. HTTP client integration</a></span></dt><dd><dl><dt><span class="section"><a href="#_synchronous_rest_template">56.5.1. Synchronous Rest Template</a></span></dt><dt><span class="section"><a href="#_asynchronous_rest_template">56.5.2. Asynchronous Rest Template</a></span></dt><dd><dl><dt><span class="section"><a href="#_multiple_asynchronous_rest_templates">Multiple Asynchronous Rest Templates</a></span></dt></dl></dd><dt><span class="section"><a href="#_traverson">56.5.3. Traverson</a></span></dt></dl></dd><dt><span class="section"><a href="#_feign">56.6. Feign</a></span></dt><dt><span class="section"><a href="#_asynchronous_communication">56.7. Asynchronous communication</a></span></dt><dd><dl><dt><span class="section"><a href="#__async_annotated_methods">56.7.1. @Async annotated methods</a></span></dt><dt><span class="section"><a href="#__scheduled_annotated_methods">56.7.2. @Scheduled annotated methods</a></span></dt><dt><span class="section"><a href="#_executor_executorservice_and_scheduledexecutorservice">56.7.3. Executor, ExecutorService and ScheduledExecutorService</a></span></dt><dd><dl><dt><span class="section"><a href="#_customization_of_executors">Customization of Executors</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_messaging">56.8. Messaging</a></span></dt><dt><span class="section"><a href="#_zuul_2">56.9. Zuul</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_running_examples">57. Running examples</a></span></dt></dl></dd><dt><span class="part"><a href="#_spring_cloud_consul">VIII. Spring Cloud Consul</a></span></dt><dd><dl><dt><span class="chapter"><a href="#spring-cloud-consul-install">58. Install Consul</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-agent">59. Consul Agent</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-discovery">60. Service Discovery with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate">60.1. How to activate</a></span></dt><dt><span class="section"><a href="#_registering_with_consul">60.2. Registering with Consul</a></span></dt><dt><span class="section"><a href="#_http_health_check">60.3. HTTP Health Check</a></span></dt><dd><dl><dt><span class="section"><a href="#_metadata_and_consul_tags">60.3.1. Metadata and Consul tags</a></span></dt><dt><span class="section"><a href="#_making_the_consul_instance_id_unique">60.3.2. Making the Consul Instance ID Unique</a></span></dt></dl></dd><dt><span class="section"><a href="#_using_the_discoveryclient">60.4. Using the DiscoveryClient</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-config">61. Distributed Configuration with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_2">61.1. How to activate</a></span></dt><dt><span class="section"><a href="#_customizing">61.2. Customizing</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-watch">61.3. Config Watch</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-format">61.4. YAML or Properties with Config</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-config-git2consul">61.5. git2consul with Config</a></span></dt><dt><span class="section"><a href="#spring-cloud-consul-failfast">61.6. Fail Fast</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-retry">62. Consul Retry</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-bus">63. Spring Cloud Bus with Consul</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_3">63.1. How to activate</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-consul-hystrix">64. Circuit Breaker with Hystrix</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-consul-turbine">65. Hystrix metrics aggregation with Turbine and Consul</a></span></dt></dl></dd><dt><span class="part"><a href="#_spring_cloud_zookeeper">IX. Spring Cloud Zookeeper</a></span></dt><dd><dl><dt><span class="chapter"><a href="#spring-cloud-zookeeper-install">66. Install Zookeeper</a></span></dt><dt><span class="chapter"><a href="#spring-cloud-zookeeper-discovery">67. Service Discovery with Zookeeper</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_4">67.1. How to activate</a></span></dt><dt><span class="section"><a href="#_registering_with_zookeeper">67.2. Registering with Zookeeper</a></span></dt><dt><span class="section"><a href="#_using_the_discoveryclient_2">67.3. Using the DiscoveryClient</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-zookeeper-netflix">68. Using Spring Cloud Zookeeper with Spring Cloud Netflix Components</a></span></dt><dd><dl><dt><span class="section"><a href="#_ribbon_with_zookeeper">68.1. Ribbon with Zookeeper</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-zookeeper-service-registry">69. Spring Cloud Zookeeper and Service Registry</a></span></dt><dd><dl><dt><span class="section"><a href="#_instance_status">69.1. Instance Status</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-zookeeper-dependencies">70. Zookeeper Dependencies</a></span></dt><dd><dl><dt><span class="section"><a href="#_using_the_zookeeper_dependencies">70.1. Using the Zookeeper Dependencies</a></span></dt><dt><span class="section"><a href="#_how_to_activate_zookeeper_dependencies">70.2. How to activate Zookeeper Dependencies</a></span></dt><dt><span class="section"><a href="#_setting_up_zookeeper_dependencies">70.3. Setting up Zookeeper Dependencies</a></span></dt><dd><dl><dt><span class="section"><a href="#_aliases">70.3.1. Aliases</a></span></dt><dt><span class="section"><a href="#_path">70.3.2. Path</a></span></dt><dt><span class="section"><a href="#_load_balancer_type">70.3.3. Load balancer type</a></span></dt><dt><span class="section"><a href="#_content_type_template_and_version">70.3.4. Content-Type template and version</a></span></dt><dt><span class="section"><a href="#_default_headers">70.3.5. Default headers</a></span></dt><dt><span class="section"><a href="#_obligatory_dependencies">70.3.6. Obligatory dependencies</a></span></dt><dt><span class="section"><a href="#_stubs">70.3.7. Stubs</a></span></dt></dl></dd><dt><span class="section"><a href="#_configuring_spring_cloud_zookeeper_dependencies">70.4. Configuring Spring Cloud Zookeeper Dependencies</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-zookeeper-dependency-watcher">71. Spring Cloud Zookeeper Dependency Watcher</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_5">71.1. How to activate</a></span></dt><dt><span class="section"><a href="#_registering_a_listener">71.2. Registering a listener</a></span></dt><dt><span class="section"><a href="#_presence_checker">71.3. Presence Checker</a></span></dt></dl></dd><dt><span class="chapter"><a href="#spring-cloud-zookeeper-config">72. Distributed Configuration with Zookeeper</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_activate_6">72.1. How to activate</a></span></dt><dt><span class="section"><a href="#_customizing_2">72.2. Customizing</a></span></dt><dt><span class="section"><a href="#_acls">72.3. ACLs</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="#_spring_cloud_security">X. Spring Cloud Security</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_quickstart">73. Quickstart</a></span></dt><dd><dl><dt><span class="section"><a href="#_oauth2_single_sign_on">73.1. OAuth2 Single Sign On</a></span></dt><dt><span class="section"><a href="#_oauth2_protected_resource">73.2. OAuth2 Protected Resource</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_more_detail">74. More Detail</a></span></dt><dd><dl><dt><span class="section"><a href="#_single_sign_on">74.1. Single Sign On</a></span></dt><dt><span class="section"><a href="#_token_relay">74.2. Token Relay</a></span></dt><dd><dl><dt><span class="section"><a href="#_client_token_relay">74.2.1. Client Token Relay</a></span></dt><dt><span class="section"><a href="#_client_token_relay_in_zuul_proxy">74.2.2. Client Token Relay in Zuul Proxy</a></span></dt><dt><span class="section"><a href="#_resource_server_token_relay">74.2.3. Resource Server Token Relay</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_configuring_authentication_downstream_of_a_zuul_proxy">75. Configuring Authentication Downstream of a Zuul Proxy</a></span></dt></dl></dd><dt><span class="part"><a href="#_spring_cloud_for_cloud_foundry">XI. Spring Cloud for Cloud Foundry</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_discovery">76. Discovery</a></span></dt><dt><span class="chapter"><a href="#_single_sign_on_2">77. Single Sign On</a></span></dt></dl></dd><dt><span class="part"><a href="#_spring_cloud_contract">XII. Spring Cloud Contract</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_spring_cloud_contract_2">78. Spring Cloud Contract</a></span></dt><dt><span class="chapter"><a href="#_spring_cloud_contract_verifier_introduction">79. Spring Cloud Contract Verifier Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#_why">79.1. Why?</a></span></dt><dd><dl><dt><span class="section"><a href="#_testing_issues">79.1.1. Testing issues</a></span></dt></dl></dd><dt><span class="section"><a href="#_purposes">79.2. Purposes</a></span></dt><dt><span class="section"><a href="#_how">79.3. How</a></span></dt><dd><dl><dt><span class="section"><a href="#_define_the_contract">79.3.1. Define the contract</a></span></dt><dt><span class="section"><a href="#_client_side">79.3.2. Client Side</a></span></dt><dt><span class="section"><a href="#_server_side">79.3.3. Server Side</a></span></dt></dl></dd><dt><span class="section"><a href="#_step_by_step_guide_to_cdc">79.4. Step by step guide to CDC</a></span></dt><dd><dl><dt><span class="section"><a href="#_technical_note">79.4.1. Technical note</a></span></dt><dt><span class="section"><a href="#_consumer_side_loan_issuance">79.4.2. Consumer side (Loan Issuance)</a></span></dt><dt><span class="section"><a href="#_producer_side_fraud_detection_server">79.4.3. Producer side (Fraud Detection server)</a></span></dt><dt><span class="section"><a href="#_consumer_side_loan_issuance_final_step">79.4.4. Consumer side (Loan Issuance) final step</a></span></dt></dl></dd><dt><span class="section"><a href="#_dependencies">79.5. Dependencies</a></span></dt><dt><span class="section"><a href="#_additional_links">79.6. Additional links</a></span></dt><dd><dl><dt><span class="section"><a href="#_spring_cloud_contract_video">79.6.1. Spring Cloud Contract video</a></span></dt><dt><span class="section"><a href="#_readings">79.6.2. Readings</a></span></dt></dl></dd><dt><span class="section"><a href="#_samples_2">79.7. Samples</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_spring_cloud_contract_verifier_setup">80. Spring Cloud Contract Verifier Setup</a></span></dt><dd><dl><dt><span class="section"><a href="#_gradle_project">80.1. Gradle Project</a></span></dt><dd><dl><dt><span class="section"><a href="#_prerequisites">80.1.1. Prerequisites</a></span></dt><dt><span class="section"><a href="#_add_gradle_plugin_with_dependencies">80.1.2. Add gradle plugin with dependencies</a></span></dt><dt><span class="section"><a href="#_gradle_and_rest_assured_3_0">80.1.3. Gradle and Rest Assured 3.0</a></span></dt><dt><span class="section"><a href="#_snapshot_versions_for_gradle">80.1.4. Snapshot versions for Gradle</a></span></dt><dt><span class="section"><a href="#_add_stubs">80.1.5. Add stubs</a></span></dt><dt><span class="section"><a href="#_run_plugin">80.1.6. Run plugin</a></span></dt><dt><span class="section"><a href="#_default_setup">80.1.7. Default setup</a></span></dt><dt><span class="section"><a href="#_configure_plugin">80.1.8. Configure plugin</a></span></dt><dt><span class="section"><a href="#_configuration_options_4">80.1.9. Configuration options</a></span></dt><dt><span class="section"><a href="#_single_base_class_for_all_tests">80.1.10. Single base class for all tests</a></span></dt><dt><span class="section"><a href="#_different_base_classes_for_contracts">80.1.11. Different base classes for contracts</a></span></dt><dt><span class="section"><a href="#_invoking_generated_tests">80.1.12. Invoking generated tests</a></span></dt><dt><span class="section"><a href="#_spring_cloud_contract_verifier_on_consumer_side">80.1.13. Spring Cloud Contract Verifier on consumer side</a></span></dt></dl></dd><dt><span class="section"><a href="#_using_in_your_maven_project">80.2. Using in your Maven project</a></span></dt><dd><dl><dt><span class="section"><a href="#_add_maven_plugin">80.2.1. Add maven plugin</a></span></dt><dt><span class="section"><a href="#_maven_and_rest_assured_3_0">80.2.2. Maven and Rest Assured 3.0</a></span></dt><dt><span class="section"><a href="#_snapshot_versions_for_maven">80.2.3. Snapshot versions for Maven</a></span></dt><dt><span class="section"><a href="#_add_stubs_2">80.2.4. Add stubs</a></span></dt><dt><span class="section"><a href="#_run_plugin_2">80.2.5. Run plugin</a></span></dt><dt><span class="section"><a href="#_configure_plugin_2">80.2.6. Configure plugin</a></span></dt><dt><span class="section"><a href="#_important_configuration_options">80.2.7. Important configuration options</a></span></dt><dt><span class="section"><a href="#_single_base_class_for_all_tests_2">80.2.8. Single base class for all tests</a></span></dt><dt><span class="section"><a href="#_different_base_classes_for_contracts_2">80.2.9. Different base classes for contracts</a></span></dt><dt><span class="section"><a href="#_invoking_generated_tests_2">80.2.10. Invoking generated tests</a></span></dt><dt><span class="section"><a href="#_faq_with_maven_plugin">80.2.11. FAQ with Maven Plugin</a></span></dt><dt><span class="section"><a href="#_maven_plugin_and_sts">80.2.12. Maven Plugin and STS</a></span></dt><dt><span class="section"><a href="#_spring_cloud_contract_verifier_on_consumer_side_2">80.2.13. Spring Cloud Contract Verifier on consumer side</a></span></dt></dl></dd><dt><span class="section"><a href="#_scenarios">80.3. Scenarios</a></span></dt><dt><span class="section"><a href="#_stubs_and_transitive_dependencies">80.4. Stubs and transitive dependencies</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_spring_cloud_contract_verifier_messaging">81. Spring Cloud Contract Verifier Messaging</a></span></dt><dd><dl><dt><span class="section"><a href="#_integrations_2">81.1. Integrations</a></span></dt><dt><span class="section"><a href="#_manual_integration_testing">81.2. Manual Integration Testing</a></span></dt><dt><span class="section"><a href="#_publisher_side_test_generation">81.3. Publisher side test generation</a></span></dt><dd><dl><dt><span class="section"><a href="#_scenario_1_no_input_message">81.3.1. Scenario 1 (no input message)</a></span></dt><dt><span class="section"><a href="#_scenario_2_output_triggered_by_input">81.3.2. Scenario 2 (output triggered by input)</a></span></dt><dt><span class="section"><a href="#_scenario_3_no_output_message">81.3.3. Scenario 3 (no output message)</a></span></dt></dl></dd><dt><span class="section"><a href="#_consumer_stub_side_generation">81.4. Consumer Stub Side generation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_spring_cloud_contract_stub_runner">82. Spring Cloud Contract Stub Runner</a></span></dt><dd><dl><dt><span class="section"><a href="#_snapshot_versions">82.1. Snapshot versions</a></span></dt><dt><span class="section"><a href="#_publishing_stubs_as_jars">82.2. Publishing stubs as JARs</a></span></dt><dt><span class="section"><a href="#_stub_runner_core">82.3. Stub Runner Core</a></span></dt><dd><dl><dt><span class="section"><a href="#_retrieving_stubs">82.3.1. Retrieving stubs</a></span></dt><dd><dl><dt><span class="section"><a href="#_stub_downloading">Stub downloading</a></span></dt><dt><span class="section"><a href="#_classpath_scanning">Classpath scanning</a></span></dt></dl></dd><dt><span class="section"><a href="#_running_stubs">82.3.2. Running stubs</a></span></dt><dd><dl><dt><span class="section"><a href="#_limitations">Limitations</a></span></dt><dt><span class="section"><a href="#_running_using_main_app">Running using main app</a></span></dt><dt><span class="section"><a href="#_http_stubs">HTTP Stubs</a></span></dt><dt><span class="section"><a href="#_viewing_registered_mappings">Viewing registered mappings</a></span></dt><dt><span class="section"><a href="#_messaging_stubs">Messaging Stubs</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_stub_runner_junit_rule">82.4. Stub Runner JUnit Rule</a></span></dt><dd><dl><dt><span class="section"><a href="#_maven_settings">82.4.1. Maven settings</a></span></dt><dt><span class="section"><a href="#_providing_fixed_ports">82.4.2. Providing fixed ports</a></span></dt><dt><span class="section"><a href="#_fluent_api">82.4.3. Fluent API</a></span></dt><dt><span class="section"><a href="#_stub_runner_with_spring">82.4.4. Stub Runner with Spring</a></span></dt></dl></dd><dt><span class="section"><a href="#_stub_runner_spring_cloud">82.5. Stub Runner Spring Cloud</a></span></dt><dd><dl><dt><span class="section"><a href="#_stubbing_service_discovery">82.5.1. Stubbing Service Discovery</a></span></dt><dd><dl><dt><span class="section"><a href="#_test_profiles_and_service_discovery">Test profiles and service discovery</a></span></dt></dl></dd><dt><span class="section"><a href="#_additional_configuration">82.5.2. Additional Configuration</a></span></dt></dl></dd><dt><span class="section"><a href="#_stub_runner_boot_application">82.6. Stub Runner Boot Application</a></span></dt><dd><dl><dt><span class="section"><a href="#_how_to_use_it">82.6.1. How to use it?</a></span></dt><dd><dl><dt><span class="section"><a href="#_stub_runner_server">Stub Runner Server</a></span></dt><dt><span class="section"><a href="#_spring_cloud_cli">Spring Cloud CLI</a></span></dt></dl></dd><dt><span class="section"><a href="#_endpoints_2">82.6.2. Endpoints</a></span></dt><dd><dl><dt><span class="section"><a href="#_http_2">HTTP</a></span></dt><dt><span class="section"><a href="#_messaging_2">Messaging</a></span></dt></dl></dd><dt><span class="section"><a href="#_example_2">82.6.3. Example</a></span></dt><dt><span class="section"><a href="#_stub_runner_boot_with_service_discovery">82.6.4. Stub Runner Boot with Service Discovery</a></span></dt></dl></dd><dt><span class="section"><a href="#_stubs_per_consumer">82.7. Stubs Per Consumer</a></span></dt><dt><span class="section"><a href="#_common">82.8. Common</a></span></dt><dd><dl><dt><span class="section"><a href="#_common_properties_for_junit_and_spring">82.8.1. Common properties for JUnit and Spring</a></span></dt><dt><span class="section"><a href="#_stub_runner_stubs_ids">82.8.2. Stub runner stubs ids</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_stub_runner_for_messaging">83. Stub Runner for Messaging</a></span></dt><dd><dl><dt><span class="section"><a href="#_stub_triggering">83.1. Stub triggering</a></span></dt><dd><dl><dt><span class="section"><a href="#_trigger_by_label">83.1.1. Trigger by label</a></span></dt><dt><span class="section"><a href="#_trigger_by_group_and_artifact_ids">83.1.2. Trigger by group and artifact ids</a></span></dt><dt><span class="section"><a href="#_trigger_by_artifact_ids">83.1.3. Trigger by artifact ids</a></span></dt><dt><span class="section"><a href="#_trigger_all_messages">83.1.4. Trigger all messages</a></span></dt></dl></dd><dt><span class="section"><a href="#_stub_runner_camel">83.2. Stub Runner Camel</a></span></dt><dd><dl><dt><span class="section"><a href="#_adding_it_to_the_project">83.2.1. Adding it to the project</a></span></dt><dt><span class="section"><a href="#_disabling_the_functionality">83.2.2. Disabling the functionality</a></span></dt><dt><span class="section"><a href="#_examples">83.2.3. Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#_stubs_structure">Stubs structure</a></span></dt><dt><span class="section"><a href="#_scenario_1_no_input_message_2">Scenario 1 (no input message)</a></span></dt><dt><span class="section"><a href="#_scenario_2_output_triggered_by_input_2">Scenario 2 (output triggered by input)</a></span></dt><dt><span class="section"><a href="#_scenario_3_input_with_no_output">Scenario 3 (input with no output)</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_stub_runner_integration">83.3. Stub Runner Integration</a></span></dt><dd><dl><dt><span class="section"><a href="#_adding_it_to_the_project_2">83.3.1. Adding it to the project</a></span></dt><dt><span class="section"><a href="#_disabling_the_functionality_2">83.3.2. Disabling the functionality</a></span></dt><dt><span class="section"><a href="#_examples_2">83.3.3. Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#_stubs_structure_2">Stubs structure</a></span></dt><dt><span class="section"><a href="#_scenario_1_no_input_message_3">Scenario 1 (no input message)</a></span></dt><dt><span class="section"><a href="#_scenario_2_output_triggered_by_input_3">Scenario 2 (output triggered by input)</a></span></dt><dt><span class="section"><a href="#_scenario_3_input_with_no_output_2">Scenario 3 (input with no output)</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_stub_runner_stream">83.4. Stub Runner Stream</a></span></dt><dd><dl><dt><span class="section"><a href="#_adding_it_to_the_project_3">83.4.1. Adding it to the project</a></span></dt><dt><span class="section"><a href="#_disabling_the_functionality_3">83.4.2. Disabling the functionality</a></span></dt><dt><span class="section"><a href="#_examples_3">83.4.3. Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#_stubs_structure_3">Stubs structure</a></span></dt><dt><span class="section"><a href="#_scenario_1_no_input_message_4">Scenario 1 (no input message)</a></span></dt><dt><span class="section"><a href="#_scenario_2_output_triggered_by_input_4">Scenario 2 (output triggered by input)</a></span></dt><dt><span class="section"><a href="#_scenario_3_input_with_no_output_3">Scenario 3 (input with no output)</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="#_stub_runner_spring_amqp">83.5. Stub Runner Spring AMQP</a></span></dt><dd><dl><dt><span class="section"><a href="#_adding_it_to_the_project_4">83.5.1. Adding it to the project</a></span></dt><dt><span class="section"><a href="#_examples_4">83.5.2. Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#_stubs_structure_4">Stubs structure</a></span></dt><dt><span class="section"><a href="#_triggering_the_message">Triggering the message</a></span></dt><dt><span class="section"><a href="#_spring_amqp_test_configuration">Spring AMQP Test Configuration</a></span></dt></dl></dd></dl></dd></dl></dd><dt><span class="chapter"><a href="#_contract_dsl">84. Contract DSL</a></span></dt><dd><dl><dt><span class="section"><a href="#_limitations_2">84.1. Limitations</a></span></dt><dt><span class="section"><a href="#_common_top_level_elements">84.2. Common Top-Level elements</a></span></dt><dd><dl><dt><span class="section"><a href="#_description">84.2.1. Description</a></span></dt><dt><span class="section"><a href="#_name">84.2.2. Name</a></span></dt><dt><span class="section"><a href="#_ignoring_contracts">84.2.3. Ignoring contracts</a></span></dt></dl></dd><dt><span class="section"><a href="#_http_top_level_elements">84.3. HTTP Top-Level Elements</a></span></dt><dt><span class="section"><a href="#_request">84.4. Request</a></span></dt><dt><span class="section"><a href="#_response">84.5. Response</a></span></dt><dt><span class="section"><a href="#_dynamic_properties">84.6. Dynamic properties</a></span></dt><dd><dl><dt><span class="section"><a href="#_dynamic_properties_inside_the_body">84.6.1. Dynamic properties inside the body</a></span></dt><dt><span class="section"><a href="#_regular_expressions">84.6.2. Regular expressions</a></span></dt><dt><span class="section"><a href="#_passing_optional_parameters">84.6.3. Passing optional parameters</a></span></dt><dt><span class="section"><a href="#_executing_custom_methods_on_server_side">84.6.4. Executing custom methods on server side</a></span></dt><dt><span class="section"><a href="#_referencing_request_from_response">84.6.5. Referencing request from response</a></span></dt><dt><span class="section"><a href="#_dynamic_properties_in_matchers_sections">84.6.6. Dynamic properties in matchers sections</a></span></dt></dl></dd><dt><span class="section"><a href="#_jax_rs_support">84.7. JAX-RS support</a></span></dt><dt><span class="section"><a href="#_async_support">84.8. Async support</a></span></dt><dt><span class="section"><a href="#_working_with_context_paths">84.9. Working with Context Paths</a></span></dt><dt><span class="section"><a href="#_messaging_top_level_elements">84.10. Messaging Top-Level Elements</a></span></dt><dd><dl><dt><span class="section"><a href="#_output_triggered_by_a_method">84.10.1. Output triggered by a method</a></span></dt><dt><span class="section"><a href="#_output_triggered_by_a_message">84.10.2. Output triggered by a message</a></span></dt><dt><span class="section"><a href="#_consumer_producer">84.10.3. Consumer / Producer</a></span></dt></dl></dd><dt><span class="section"><a href="#_multiple_contracts_in_one_file">84.11. Multiple contracts in one file</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_customization">85. Customization</a></span></dt><dd><dl><dt><span class="section"><a href="#_extending_the_dsl">85.1. Extending the DSL</a></span></dt><dd><dl><dt><span class="section"><a href="#_common_jar">85.1.1. Common JAR</a></span></dt><dt><span class="section"><a href="#_adding_the_dependency_to_project">85.1.2. Adding the dependency to project</a></span></dt><dt><span class="section"><a href="#_test_dependency_in_project_s_dependencies">85.1.3. Test dependency in project’s dependencies</a></span></dt><dt><span class="section"><a href="#_test_dependency_in_plugin_s_dependencies">85.1.4. Test dependency in plugin’s dependencies</a></span></dt><dt><span class="section"><a href="#_referencing_classes_in_dsls">85.1.5. Referencing classes in DSLs</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_pluggable_architecture">86. Pluggable architecture</a></span></dt><dd><dl><dt><span class="section"><a href="#_custom_contract_converter">86.1. Custom contract converter</a></span></dt><dd><dl><dt><span class="section"><a href="#_pact_converter">86.1.1. Pact converter</a></span></dt><dt><span class="section"><a href="#_pact_contract">86.1.2. Pact contract</a></span></dt><dt><span class="section"><a href="#_pact_for_producers">86.1.3. Pact for producers</a></span></dt><dt><span class="section"><a href="#_pact_for_consumers">86.1.4. Pact for consumers</a></span></dt></dl></dd><dt><span class="section"><a href="#_custom_test_generator">86.2. Custom test generator</a></span></dt><dt><span class="section"><a href="#_custom_stub_generator">86.3. Custom stub generator</a></span></dt><dt><span class="section"><a href="#_custom_stub_runner">86.4. Custom Stub Runner</a></span></dt><dt><span class="section"><a href="#_custom_stub_downloader">86.5. Custom Stub Downloader</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_spring_cloud_contract_wiremock">87. Spring Cloud Contract WireMock</a></span></dt><dd><dl><dt><span class="section"><a href="#_registering_stubs_automatically">87.1. Registering Stubs Automatically</a></span></dt><dt><span class="section"><a href="#_using_files_to_specify_the_stub_bodies">87.2. Using Files to Specify the Stub Bodies</a></span></dt><dt><span class="section"><a href="#_alternative_using_junit_rules">87.3. Alternative: Using JUnit Rules</a></span></dt><dt><span class="section"><a href="#_relaxed_ssl_validation_for_rest_template">87.4. Relaxed SSL Validation for Rest Template</a></span></dt><dt><span class="section"><a href="#_wiremock_and_spring_mvc_mocks">87.5. WireMock and Spring MVC Mocks</a></span></dt><dt><span class="section"><a href="#_generating_stubs_using_restdocs">87.6. Generating Stubs using RestDocs</a></span></dt><dt><span class="section"><a href="#_generating_contracts_using_restdocs">87.7. Generating Contracts using RestDocs</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_links">88. Links</a></span></dt></dl></dd><dt><span class="part"><a href="#_spring_cloud_vault">XIII. Spring Cloud Vault</a></span></dt><dd><dl><dt><span class="chapter"><a href="#_quick_start_3">89. Quick Start</a></span></dt><dt><span class="chapter"><a href="#_client_side_usage_2">90. Client Side Usage</a></span></dt><dd><dl><dt><span class="section"><a href="#_authentication_2">90.1. Authentication</a></span></dt></dl></dd><dt><span class="chapter"><a href="#vault.config.authentication">91. Authentication methods</a></span></dt><dd><dl><dt><span class="section"><a href="#vault.config.authentication.token">91.1. Token authentication</a></span></dt><dt><span class="section"><a href="#vault.config.authentication.appid">91.2. AppId authentication</a></span></dt><dd><dl><dt><span class="section"><a href="#_custom_userid">91.2.1. Custom UserId</a></span></dt></dl></dd><dt><span class="section"><a href="#_approle_authentication">91.3. AppRole authentication</a></span></dt><dt><span class="section"><a href="#vault.config.authentication.awsec2">91.4. AWS-EC2 authentication</a></span></dt><dt><span class="section"><a href="#vault.config.authentication.clientcert">91.5. TLS certificate authentication</a></span></dt><dt><span class="section"><a href="#vault.config.authentication.cubbyhole">91.6. Cubbyhole authentication</a></span></dt></dl></dd><dt><span class="chapter"><a href="#vault.config.backends">92. Secret Backends</a></span></dt><dd><dl><dt><span class="section"><a href="#vault.config.backends.generic">92.1. Generic Backend</a></span></dt><dt><span class="section"><a href="#vault.config.backends.consul">92.2. Consul</a></span></dt><dt><span class="section"><a href="#vault.config.backends.rabbitmq">92.3. RabbitMQ</a></span></dt><dt><span class="section"><a href="#vault.config.backends.aws">92.4. AWS</a></span></dt></dl></dd><dt><span class="chapter"><a href="#vault.config.backends.database-backends">93. Database backends</a></span></dt><dd><dl><dt><span class="section"><a href="#vault.config.backends.cassandra">93.1. Apache Cassandra</a></span></dt><dt><span class="section"><a href="#vault.config.backends.mongodb">93.2. MongoDB</a></span></dt><dt><span class="section"><a href="#vault.config.backends.mysql">93.3. MySQL</a></span></dt><dt><span class="section"><a href="#vault.config.backends.postgresql">93.4. PostgreSQL</a></span></dt></dl></dd><dt><span class="chapter"><a href="#vault.config.fail-fast">94. Vault Client Fail Fast</a></span></dt><dt><span class="chapter"><a href="#vault.config.ssl">95. Vault Client SSL configuration</a></span></dt><dt><span class="chapter"><a href="#vault-lease-renewal">96. Lease lifecycle management (renewal and revocation)</a></span></dt></dl></dd><dt><span class="part"><a href="#_appendix_compendium_of_configuration_properties">XIV. Appendix: Compendium of Configuration Properties</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="d0e9" href="#d0e9"></a></h1></div></div></div><p>Spring Cloud provides tools for developers to quickly build some of
|
|
the common patterns in distributed systems (e.g. configuration
|
|
management, service discovery, circuit breakers, intelligent routing,
|
|
micro-proxy, control bus). Coordination of
|
|
distributed systems leads to boiler plate patterns, and using Spring
|
|
Cloud developers can quickly stand up services and applications that
|
|
implement those patterns. They will work well in any distributed
|
|
environment, including the developer’s own laptop, bare metal data
|
|
centres, and managed platforms such as Cloud Foundry.</p><p>Version: Dalston.SR4</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_features" href="#_features"></a>1. Features</h1></div></div></div><p>Spring Cloud focuses on providing good out of box experience for typical use cases
|
|
and extensibility mechanism to cover others.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Distributed/versioned configuration</li><li class="listitem">Service registration and discovery</li><li class="listitem">Routing</li><li class="listitem">Service-to-service calls</li><li class="listitem">Load balancing</li><li class="listitem">Circuit Breakers</li><li class="listitem">Distributed messaging</li></ul></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_cloud_native_applications" href="#_cloud_native_applications"></a>Part I. Cloud Native Applications</h1></div></div></div><div class="partintro"><div></div><p><a class="link" href="http://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook" target="_top">Cloud Native</a> is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development. A related discipline is that of building <a class="link" href="http://12factor.net/" target="_top">12-factor Apps</a> in which development practices are aligned with delivery and operations goals, for instance by using declarative programming and management and monitoring. Spring Cloud facilitates these styles of development in a number of specific ways and the starting point is a set of features that all components in a distributed system either need or need easy access to when required.</p><p>Many of those features are covered by <a class="link" href="http://projects.spring.io/spring-boot" target="_top">Spring Boot</a>, which we build on in Spring Cloud. Some more are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons. Spring Cloud Context provides utilities and special services for the <code class="literal">ApplicationContext</code> of a Spring Cloud application (bootstrap context, encryption, refresh scope and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (eg. Spring Cloud Netflix vs. Spring Cloud Consul).</p><p>If you are getting an exception due to "Illegal key size" and you are using Sun’s JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. See the following links for more information:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html" target="_top">Java 6 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html" target="_top">Java 7 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html" target="_top">Java 8 JCE</a></li></ul></div><p>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at <a class="link" href="https://github.com/spring-cloud/spring-cloud-commons/tree/master/docs/src/main/asciidoc" target="_top">github</a>.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_context_application_context_services" href="#_spring_cloud_context_application_context_services"></a>2. Spring Cloud Context: Application Context Services</h2></div></div></div><p>Spring Boot has an opinionated view of how to build an application
|
|
with Spring: for instance it has conventional locations for common
|
|
configuration file, and endpoints for common management and monitoring
|
|
tasks. Spring Cloud builds on top of that and adds a few features that
|
|
probably all components in a system would use or occasionally need.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_the_bootstrap_application_context" href="#_the_bootstrap_application_context"></a>2.1 The Bootstrap Application Context</h2></div></div></div><p>A Spring Cloud application operates by creating a "bootstrap"
|
|
context, which is a parent context for the main application. Out of
|
|
the box it is responsible for loading configuration properties from
|
|
the external sources, and also decrypting properties in the local
|
|
external configuration files. The two contexts share an <code class="literal">Environment</code>
|
|
which is the source of external properties for any Spring
|
|
application. Bootstrap properties are added with high precedence, so
|
|
they cannot be overridden by local configuration, by default.</p><p>The bootstrap context uses a different convention for locating
|
|
external configuration than the main application context, so instead
|
|
of <code class="literal">application.yml</code> (or <code class="literal">.properties</code>) you use <code class="literal">bootstrap.yml</code>,
|
|
keeping the external configuration for bootstrap and main context
|
|
nicely separate. Example:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
application:
|
|
name: foo
|
|
cloud:
|
|
config:
|
|
uri: ${SPRING_CONFIG_URI:http://localhost:8888}</pre><p>
|
|
</p><p>It is a good idea to set the <code class="literal">spring.application.name</code> (in
|
|
<code class="literal">bootstrap.yml</code> or <code class="literal">application.yml</code>) if your application needs any
|
|
application-specific configuration from the server.</p><p>You can disable the bootstrap process completely by setting
|
|
<code class="literal">spring.cloud.bootstrap.enabled=false</code> (e.g. in System properties).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_application_context_hierarchies" href="#_application_context_hierarchies"></a>2.2 Application Context Hierarchies</h2></div></div></div><p>If you build an application context from <code class="literal">SpringApplication</code> or
|
|
<code class="literal">SpringApplicationBuilder</code>, then the Bootstrap context is added as a
|
|
parent to that context. It is a feature of Spring that child contexts
|
|
inherit property sources and profiles from their parent, so the "main"
|
|
application context will contain additional property sources, compared
|
|
to building the same context without Spring Cloud Config. The
|
|
additional property sources are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">"bootstrap": an optional <code class="literal">CompositePropertySource</code> appears with high
|
|
priority if any <code class="literal">PropertySourceLocators</code> are found in the Bootstrap
|
|
context, and they have non-empty properties. An example would be
|
|
properties from the Spring Cloud Config Server. See
|
|
<a class="link" href="#customizing-bootstrap-property-sources" title="2.6 Customizing the Bootstrap Property Sources">below</a> for instructions
|
|
on how to customize the contents of this property source.</li><li class="listitem">"applicationConfig: [classpath:bootstrap.yml]" (and friends if
|
|
Spring profiles are active). If you have a <code class="literal">bootstrap.yml</code> (or
|
|
properties) then those properties are used to configure the Bootstrap
|
|
context, and then they get added to the child context when its parent
|
|
is set. They have lower precedence than the <code class="literal">application.yml</code> (or
|
|
properties) and any other property sources that are added to the child
|
|
as a normal part of the process of creating a Spring Boot
|
|
application. See <a class="link" href="#customizing-bootstrap-properties" title="2.3 Changing the Location of Bootstrap Properties">below</a> for
|
|
instructions on how to customize the contents of these property
|
|
sources.</li></ul></div><p>Because of the ordering rules of property sources the "bootstrap"
|
|
entries take precedence, but note that these do not contain any data
|
|
from <code class="literal">bootstrap.yml</code>, which has very low precedence, but can be used
|
|
to set defaults.</p><p>You can extend the context hierarchy by simply setting the parent
|
|
context of any <code class="literal">ApplicationContext</code> you create, e.g. using its own
|
|
interface, or with the <code class="literal">SpringApplicationBuilder</code> convenience methods
|
|
(<code class="literal">parent()</code>, <code class="literal">child()</code> and <code class="literal">sibling()</code>). The bootstrap context will be
|
|
the parent of the most senior ancestor that you create yourself.
|
|
Every context in the hierarchy will have its own "bootstrap" property
|
|
source (possibly empty) to avoid promoting values inadvertently from
|
|
parents down to their descendants. Every context in the hierarchy can
|
|
also (in principle) have a different <code class="literal">spring.application.name</code> and
|
|
hence a different remote property source if there is a Config
|
|
Server. Normal Spring application context behaviour rules apply to
|
|
property resolution: properties from a child context override those in
|
|
the parent, by name and also by property source name (if the child has
|
|
a property source with the same name as the parent, the one from the
|
|
parent is not included in the child).</p><p>Note that the <code class="literal">SpringApplicationBuilder</code> allows you to share an
|
|
<code class="literal">Environment</code> amongst the whole hierarchy, but that is not the
|
|
default. Thus, sibling contexts in particular do not need to have the
|
|
same profiles or property sources, even though they will share common
|
|
things with their parent.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="customizing-bootstrap-properties" href="#customizing-bootstrap-properties"></a>2.3 Changing the Location of Bootstrap Properties</h2></div></div></div><p>The <code class="literal">bootstrap.yml</code> (or <code class="literal">.properties</code>) location can be specified using
|
|
<code class="literal">spring.cloud.bootstrap.name</code> (default "bootstrap") or
|
|
<code class="literal">spring.cloud.bootstrap.location</code> (default empty), e.g. in System
|
|
properties. Those properties behave like the <code class="literal">spring.config.*</code>
|
|
variants with the same name, in fact they are used to set up the
|
|
bootstrap <code class="literal">ApplicationContext</code> by setting those properties in its
|
|
<code class="literal">Environment</code>. If there is an active profile (from
|
|
<code class="literal">spring.profiles.active</code> or through the <code class="literal">Environment</code> API in the
|
|
context you are building) then properties in that profile will be
|
|
loaded as well, just like in a regular Spring Boot app, e.g. from
|
|
<code class="literal">bootstrap-development.properties</code> for a "development" profile.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="overriding-bootstrap-properties" href="#overriding-bootstrap-properties"></a>2.4 Overriding the Values of Remote Properties</h2></div></div></div><p>The property sources that are added to you application by the
|
|
bootstrap context are often "remote" (e.g. from a Config Server), and
|
|
by default they cannot be overridden locally, except on the command
|
|
line. If you want to allow your applications to override the remote
|
|
properties with their own System properties or config files, the
|
|
remote property source has to grant it permission by setting
|
|
<code class="literal">spring.cloud.config.allowOverride=true</code> (it doesn’t work to set this
|
|
locally). Once that flag is set there are some finer grained settings
|
|
to control the location of the remote properties in relation to System
|
|
properties and the application’s local configuration:
|
|
<code class="literal">spring.cloud.config.overrideNone=true</code> to override with any local
|
|
property source, and
|
|
<code class="literal">spring.cloud.config.overrideSystemProperties=false</code> if only System
|
|
properties and env vars should override the remote settings, but not
|
|
the local config files.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customizing_the_bootstrap_configuration" href="#_customizing_the_bootstrap_configuration"></a>2.5 Customizing the Bootstrap Configuration</h2></div></div></div><p>The bootstrap context can be trained to do anything you like by adding
|
|
entries to <code class="literal">/META-INF/spring.factories</code> under the key
|
|
<code class="literal">org.springframework.cloud.bootstrap.BootstrapConfiguration</code>. This is
|
|
a comma-separated list of Spring <code class="literal">@Configuration</code> classes which will
|
|
be used to create the context. Any beans that you want to be available
|
|
to the main application context for autowiring can be created here,
|
|
and also there is a special contract for <code class="literal">@Beans</code> of type
|
|
<code class="literal">ApplicationContextInitializer</code>. Classes can be marked with an <code class="literal">@Order</code>
|
|
if you want to control the startup sequence (the default order is
|
|
"last").</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Be careful when adding custom <code class="literal">BootstrapConfiguration</code> that the
|
|
classes you add are not <code class="literal">@ComponentScanned</code> by mistake into your
|
|
"main" application context, where they might not be needed.
|
|
Use a separate package name for boot configuration classes that is
|
|
not already covered by your <code class="literal">@ComponentScan</code> or <code class="literal">@SpringBootApplication</code>
|
|
annotated configuration classes.</p></td></tr></table></div><p>The bootstrap process ends by injecting initializers into the main
|
|
<code class="literal">SpringApplication</code> instance (i.e. the normal Spring Boot startup
|
|
sequence, whether it is running as a standalone app or deployed in an
|
|
application server). First a bootstrap context is created from the
|
|
classes found in <code class="literal">spring.factories</code> and then all <code class="literal">@Beans</code> of type
|
|
<code class="literal">ApplicationContextInitializer</code> are added to the main
|
|
<code class="literal">SpringApplication</code> before it is started.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="customizing-bootstrap-property-sources" href="#customizing-bootstrap-property-sources"></a>2.6 Customizing the Bootstrap Property Sources</h2></div></div></div><p>The default property source for external configuration added by the
|
|
bootstrap process is the Config Server, but you can add additional
|
|
sources by adding beans of type <code class="literal">PropertySourceLocator</code> to the
|
|
bootstrap context (via <code class="literal">spring.factories</code>). You could use this to
|
|
insert additional properties from a different server, or from a
|
|
database, for instance.</p><p>As an example, consider the following trivial custom locator:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomPropertySourceLocator <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> PropertySourceLocator {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> PropertySource<?> locate(Environment environment) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MapPropertySource(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"customProperty"</span>,
|
|
Collections.<String, Object>singletonMap(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"property.from.sample.custom.source"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"worked as intended"</span>));
|
|
}
|
|
|
|
}</pre><p>The <code class="literal">Environment</code> that is passed in is the one for the
|
|
<code class="literal">ApplicationContext</code> about to be created, i.e. the one that we are
|
|
supplying additional property sources for. It will already have its
|
|
normal Spring Boot-provided property sources, so you can use those to
|
|
locate a property source specific to this <code class="literal">Environment</code> (e.g. by
|
|
keying it on the <code class="literal">spring.application.name</code>, as is done in the default
|
|
Config Server property source locator).</p><p>If you create a jar with this class in it and then add a
|
|
<code class="literal">META-INF/spring.factories</code> containing:</p><pre class="screen">org.springframework.cloud.bootstrap.BootstrapConfiguration=sample.custom.CustomPropertySourceLocator</pre><p>then the "customProperty" <code class="literal">PropertySource</code> will show up in any
|
|
application that includes that jar on its classpath.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_environment_changes" href="#_environment_changes"></a>2.7 Environment Changes</h2></div></div></div><p>The application will listen for an <code class="literal">EnvironmentChangeEvent</code> and react
|
|
to the change in a couple of standard ways (additional
|
|
<code class="literal">ApplicationListeners</code> can be added as <code class="literal">@Beans</code> by the user in the
|
|
normal way). When an <code class="literal">EnvironmentChangeEvent</code> is observed it will
|
|
have a list of key values that have changed, and the application will
|
|
use those to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Re-bind any <code class="literal">@ConfigurationProperties</code> beans in the context</li><li class="listitem">Set the logger levels for any properties in <code class="literal">logging.level.*</code></li></ul></div><p>Note that the Config Client does not by default poll for changes in
|
|
the <code class="literal">Environment</code>, and generally we would not recommend that approach
|
|
for detecting changes (although you could set it up with a
|
|
<code class="literal">@Scheduled</code> annotation). If you have a scaled-out client application
|
|
then it is better to broadcast the <code class="literal">EnvironmentChangeEvent</code> to all
|
|
the instances instead of having them polling for changes (e.g. using
|
|
the <a class="link" href="https://github.com/spring-cloud/spring-cloud-bus" target="_top">Spring Cloud
|
|
Bus</a>).</p><p>The <code class="literal">EnvironmentChangeEvent</code> covers a large class of refresh use
|
|
cases, as long as you can actually make a change to the <code class="literal">Environment</code>
|
|
and publish the event (those APIs are public and part of core
|
|
Spring). You can verify the changes are bound to
|
|
<code class="literal">@ConfigurationProperties</code> beans by visiting the <code class="literal">/configprops</code>
|
|
endpoint (normal Spring Boot Actuator feature). For instance a
|
|
<code class="literal">DataSource</code> can have its <code class="literal">maxPoolSize</code> changed at runtime (the
|
|
default <code class="literal">DataSource</code> created by Spring Boot is an
|
|
<code class="literal">@ConfigurationProperties</code> bean) and grow capacity
|
|
dynamically. Re-binding <code class="literal">@ConfigurationProperties</code> does not cover
|
|
another large class of use cases, where you need more control over the
|
|
refresh, and where you need a change to be atomic over the whole
|
|
<code class="literal">ApplicationContext</code>. To address those concerns we have
|
|
<code class="literal">@RefreshScope</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_refresh_scope" href="#_refresh_scope"></a>2.8 Refresh Scope</h2></div></div></div><p>A Spring <code class="literal">@Bean</code> that is marked as <code class="literal">@RefreshScope</code> will get special
|
|
treatment when there is a configuration change. This addresses the
|
|
problem of stateful beans that only get their configuration injected
|
|
when they are initialized. For instance if a <code class="literal">DataSource</code> has open
|
|
connections when the database URL is changed via the <code class="literal">Environment</code>, we
|
|
probably want the holders of those connections to be able to complete
|
|
what they are doing. Then the next time someone borrows a connection
|
|
from the pool he gets one with the new URL.</p><p>Refresh scope beans are lazy proxies that initialize when they are
|
|
used (i.e. when a method is called), and the scope acts as a cache of
|
|
initialized values. To force a bean to re-initialize on the next
|
|
method call you just need to invalidate its cache entry.</p><p>The <code class="literal">RefreshScope</code> is a bean in the context and it has a public method
|
|
<code class="literal">refreshAll()</code> to refresh all beans in the scope by clearing the
|
|
target cache. There is also a <code class="literal">refresh(String)</code> method to refresh an
|
|
individual bean by name. This functionality is exposed in the
|
|
<code class="literal">/refresh</code> endpoint (over HTTP or JMX).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p><code class="literal">@RefreshScope</code> works (technically) on an <code class="literal">@Configuration</code>
|
|
class, but it might lead to surprising behaviour: e.g. it does <span class="strong"><strong>not</strong></span>
|
|
mean that all the <code class="literal">@Beans</code> defined in that class are themselves
|
|
<code class="literal">@RefreshScope</code>. Specifically, anything that depends on those beans
|
|
cannot rely on them being updated when a refresh is initiated, unless
|
|
it is itself in <code class="literal">@RefreshScope</code> (in which it will be rebuilt on a
|
|
refresh and its dependencies re-injected, at which point they will be
|
|
re-initialized from the refreshed <code class="literal">@Configuration</code>).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_encryption_and_decryption" href="#_encryption_and_decryption"></a>2.9 Encryption and Decryption</h2></div></div></div><p>Spring Cloud has an <code class="literal">Environment</code> pre-processor for decrypting
|
|
property values locally. It follows the same rules as the Config
|
|
Server, and has the same external configuration via <code class="literal">encrypt.*</code>. Thus
|
|
you can use encrypted values in the form <code class="literal">{cipher}*</code> and as long as
|
|
there is a valid key then they will be decrypted before the main
|
|
application context gets the <code class="literal">Environment</code>. To use the encryption
|
|
features in an application you need to include Spring Security RSA in
|
|
your classpath (Maven co-ordinates
|
|
"org.springframework.security:spring-security-rsa") and you also need
|
|
the full strength JCE extensions in your JVM.</p><p>If you are getting an exception due to "Illegal key size" and you are using Sun’s JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. See the following links for more information:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html" target="_top">Java 6 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html" target="_top">Java 7 JCE</a></li><li class="listitem"><a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html" target="_top">Java 8 JCE</a></li></ul></div><p>Extract files into JDK/jre/lib/security folder (whichever version of JRE/JDK x64/x86 you are using).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_endpoints" href="#_endpoints"></a>2.10 Endpoints</h2></div></div></div><p>For a Spring Boot Actuator application there are some additional management endpoints:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">POST to <code class="literal">/env</code> to update the <code class="literal">Environment</code> and rebind <code class="literal">@ConfigurationProperties</code> and log levels</li><li class="listitem"><code class="literal">/refresh</code> for re-loading the boot strap context and refreshing the <code class="literal">@RefreshScope</code> beans</li><li class="listitem"><code class="literal">/restart</code> for closing the <code class="literal">ApplicationContext</code> and restarting it (disabled by default)</li><li class="listitem"><code class="literal">/pause</code> and <code class="literal">/resume</code> for calling the <code class="literal">Lifecycle</code> methods (<code class="literal">stop()</code> and <code class="literal">start()</code> on the <code class="literal">ApplicationContext</code>)</li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_commons_common_abstractions" href="#_spring_cloud_commons_common_abstractions"></a>3. Spring Cloud Commons: Common Abstractions</h2></div></div></div><p>Patterns such as service discovery, load balancing and circuit breakers lend themselves to a common abstraction layer that can be consumed by all Spring Cloud clients, independent of the implementation (e.g. discovery via Eureka or Consul).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="__enablediscoveryclient" href="#__enablediscoveryclient"></a>3.1 @EnableDiscoveryClient</h2></div></div></div><p>Commons provides the <code class="literal">@EnableDiscoveryClient</code> annotation. This looks for implementations of the <code class="literal">DiscoveryClient</code> interface via <code class="literal">META-INF/spring.factories</code>. Implementations of Discovery Client will add a configuration class to <code class="literal">spring.factories</code> under the <code class="literal">org.springframework.cloud.client.discovery.EnableDiscoveryClient</code> key. Examples of <code class="literal">DiscoveryClient</code> implementations: are <a class="link" href="http://cloud.spring.io/spring-cloud-netflix/" target="_top">Spring Cloud Netflix Eureka</a>, <a class="link" href="http://cloud.spring.io/spring-cloud-consul/" target="_top">Spring Cloud Consul Discovery</a> and <a class="link" href="http://cloud.spring.io/spring-cloud-zookeeper/" target="_top">Spring Cloud Zookeeper Discovery</a>.</p><p>By default, implementations of <code class="literal">DiscoveryClient</code> will auto-register the local Spring Boot server with the remote discovery server. This can be disabled by setting <code class="literal">autoRegister=false</code> in <code class="literal">@EnableDiscoveryClient</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_serviceregistry" href="#_serviceregistry"></a>3.2 ServiceRegistry</h2></div></div></div><p>Commons now provides a <code class="literal">ServiceRegistry</code> interface which provides methods like <code class="literal">register(Registration)</code> and <code class="literal">deregister(Registration)</code> which allow you to provide custom registered services. <code class="literal">Registration</code> is a marker interface.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableDiscoveryClient(autoRegister=false)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> ServiceRegistry registry;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MyConfiguration(ServiceRegistry registry) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.registry = registry;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// called via some external process, such as an event or a custom actuator endpoint</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> register() {
|
|
Registration registration = constructRegistration();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.registry.register(registration);
|
|
}
|
|
}</pre><p>Each <code class="literal">ServiceRegistry</code> implementation has its own <code class="literal">Registry</code> implementation.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_serviceregistry_auto_registration" href="#_serviceregistry_auto_registration"></a>3.2.1 ServiceRegistry Auto-Registration</h3></div></div></div><p>By default, the <code class="literal">ServiceRegistry</code> implementation will auto-register the running service. To disable that behavior, there are two methods. You can set <code class="literal">@EnableDiscoveryClient(autoRegister=false)</code> to permanently disable auto-registration. You can also set <code class="literal">spring.cloud.service-registry.auto-registration.enabled=false</code> to disable the behavior via configuration.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_service_registry_actuator_endpoint" href="#_service_registry_actuator_endpoint"></a>3.2.2 Service Registry Actuator Endpoint</h3></div></div></div><p>A <code class="literal">/service-registry</code> actuator endpoint is provided by Commons. This endpoint relys on a <code class="literal">Registration</code> bean in the Spring Application Context. Calling <code class="literal">/service-registry/instance-status</code> via a GET will return the status of the <code class="literal">Registration</code>. A POST to the same endpoint with a <code class="literal">String</code> body will change the status of the current <code class="literal">Registration</code> to the new value. Please see the documentation of the <code class="literal">ServiceRegistry</code> implementation you are using for the allowed values for updating the status and the values retured for the status.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_resttemplate_as_a_load_balancer_client" href="#_spring_resttemplate_as_a_load_balancer_client"></a>3.3 Spring RestTemplate as a Load Balancer Client</h2></div></div></div><p><code class="literal">RestTemplate</code> can be automatically configured to use ribbon. To create a load balanced <code class="literal">RestTemplate</code> create a <code class="literal">RestTemplate</code> <code class="literal">@Bean</code> and use the <code class="literal">@LoadBalanced</code> qualifier.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>A <code class="literal">RestTemplate</code> bean is no longer created via auto configuration. It must be created by individual applications.</p></td></tr></table></div><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@LoadBalanced</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
RestTemplate restTemplate() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> RestTemplate();
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RestTemplate restTemplate;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doOtherStuff() {
|
|
String results = restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://stores/stores"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> results;
|
|
}
|
|
}</pre><p>The URI needs to use a virtual host name (ie. service name, not a host name).
|
|
The Ribbon client is used to create a full physical address. See
|
|
<a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/ribbon/RibbonAutoConfiguration.java" target="_top">RibbonAutoConfiguration</a>
|
|
for details of how the <code class="literal">RestTemplate</code> is set up.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_retrying_failed_requests" href="#_retrying_failed_requests"></a>3.3.1 Retrying Failed Requests</h3></div></div></div><p>A load balanced <code class="literal">RestTemplate</code> can be configured to retry failed requests.
|
|
By default this logic is disabled, you can enable it by adding <a class="link" href="https://github.com/spring-projects/spring-retry" target="_top">Spring Retry</a> to your application’s classpath. The load balanced <code class="literal">RestTemplate</code> will
|
|
honor some of the Ribbon configuration values related to retrying failed requests. If
|
|
you would like to disable the retry logic with Spring Retry on the classpath
|
|
you can set <code class="literal">spring.cloud.loadbalancer.retry.enabled=false</code>.
|
|
The properties you can use are <code class="literal">client.ribbon.MaxAutoRetries</code>,
|
|
<code class="literal">client.ribbon.MaxAutoRetriesNextServer</code>, and <code class="literal">client.ribbon.OkToRetryOnAllOperations</code>.
|
|
See the <a class="link" href="https://github.com/Netflix/ribbon/wiki/Getting-Started#the-properties-file-sample-clientproperties" target="_top">Ribbon documentation</a>
|
|
for a description of what there properties do.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p><code class="literal">client</code> in the above examples should be replaced with your Ribbon client’s
|
|
name.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_multiple_resttemplate_objects" href="#_multiple_resttemplate_objects"></a>3.4 Multiple RestTemplate objects</h2></div></div></div><p>If you want a <code class="literal">RestTemplate</code> that is not load balanced, create a <code class="literal">RestTemplate</code>
|
|
bean and inject it as normal. To access the load balanced <code class="literal">RestTemplate</code> use
|
|
the <code class="literal">@LoadBalanced</code> qualifier when you create your <code class="literal">@Bean</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Notice the <code class="literal">@Primary</code> annotation on the plain <code class="literal">RestTemplate</code> declaration in the example below, to disambiguate the unqualified <code class="literal">@Autowired</code> injection.</p></td></tr></table></div><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyConfiguration {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@LoadBalanced</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
RestTemplate loadBalanced() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> RestTemplate();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Primary</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
RestTemplate restTemplate() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> RestTemplate();
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RestTemplate restTemplate;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@LoadBalanced</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RestTemplate loadBalanced;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doOtherStuff() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> loadBalanced.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://stores/stores"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doStuff() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://example.com"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
}
|
|
}</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you see errors like <code class="literal">java.lang.IllegalArgumentException: Can not set org.springframework.web.client.RestTemplate field com.my.app.Foo.restTemplate to com.sun.proxy.$Proxy89</code> try injecting <code class="literal">RestOperations</code> instead or setting <code class="literal">spring.aop.proxyTargetClass=true</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ignore-network-interfaces" href="#ignore-network-interfaces"></a>3.5 Ignore Network Interfaces</h2></div></div></div><p>Sometimes it is useful to ignore certain named network interfaces so they can be excluded from Service Discovery registration (eg. running in a Docker container). A list of regular expressions can be set that will cause the desired network interfaces to be ignored. The following configuration will ignore the "docker0" interface and all interfaces that start with "veth".</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
inetutils:
|
|
ignoredInterfaces:
|
|
- docker0
|
|
- veth.*</pre><p>
|
|
</p><p>You can also force to use only specified network addresses using list of regular expressions:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
inetutils:
|
|
preferredNetworks:
|
|
- 192.168
|
|
- 10.0</pre><p>
|
|
</p><p>You can also force to use only site local addresses. See <a class="link" href="https://docs.oracle.com/javase/8/docs/api/java/net/Inet4Address.html#isSiteLocalAddress--" target="_top">Inet4Address.html.isSiteLocalAddress()</a> for more details what is site local address.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
inetutils:
|
|
useOnlySiteLocalInterfaces: true</pre><p>
|
|
</p></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_config" href="#_spring_cloud_config"></a>Part II. Spring Cloud Config</h1></div></div></div><div class="partintro"><div></div><p><span class="strong"><strong>Dalston.SR4</strong></span></p><p>Spring Cloud Config provides server and client-side support for externalized configuration in a distributed system. With the Config Server you have a central place to manage external properties for applications across all environments. The concepts on both client and server map identically to the Spring <code class="literal">Environment</code> and <code class="literal">PropertySource</code> abstractions, so they fit very well with Spring applications, but can be used with any application running in any language. As an application moves through the deployment pipeline from dev to test and into production you can manage the configuration between those environments and be certain that applications have everything they need to run when they migrate. The default implementation of the server storage backend uses git so it easily supports labelled versions of configuration environments, as well as being accessible to a wide range of tooling for managing the content. It is easy to add alternative implementations and plug them in with Spring configuration.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_quick_start" href="#_quick_start"></a>4. Quick Start</h2></div></div></div><p>Start the server:</p><pre class="screen">$ cd spring-cloud-config-server
|
|
$ ../mvnw spring-boot:run</pre><p>The server is a Spring Boot application so you can run it from your
|
|
IDE instead if you prefer (the main class is
|
|
<code class="literal">ConfigServerApplication</code>). Then try out a client:</p><pre class="screen">$ curl localhost:8888/foo/development
|
|
{"name":"development","label":"master","propertySources":[
|
|
{"name":"https://github.com/scratches/config-repo/foo-development.properties","source":{"bar":"spam"}},
|
|
{"name":"https://github.com/scratches/config-repo/foo.properties","source":{"foo":"bar"}}
|
|
]}</pre><p>The default strategy for locating property sources is to clone a git
|
|
repository (at <code class="literal">spring.cloud.config.server.git.uri</code>) and use it to
|
|
initialize a mini <code class="literal">SpringApplication</code>. The mini-application’s
|
|
<code class="literal">Environment</code> is used to enumerate property sources and publish them
|
|
via a JSON endpoint.</p><p>The HTTP service has resources in the form:</p><pre class="screen">/{application}/{profile}[/{label}]
|
|
/{application}-{profile}.yml
|
|
/{label}/{application}-{profile}.yml
|
|
/{application}-{profile}.properties
|
|
/{label}/{application}-{profile}.properties</pre><p>where the "application" is injected as the <code class="literal">spring.config.name</code> in the
|
|
<code class="literal">SpringApplication</code> (i.e. what is normally "application" in a regular
|
|
Spring Boot app), "profile" is an active profile (or comma-separated
|
|
list of properties), and "label" is an optional git label (defaults to
|
|
"master".)</p><p>Spring Cloud Config Server pulls configuration for remote clients
|
|
from a git repository (which must be provided):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo</pre><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_client_side_usage" href="#_client_side_usage"></a>4.1 Client Side Usage</h2></div></div></div><p>To use these features in an application, just build it as a Spring
|
|
Boot application that depends on spring-cloud-config-client (e.g. see
|
|
the test cases for the config-client, or the sample app). The most
|
|
convenient way to add the dependency is via a Spring Boot starter
|
|
<code class="literal">org.springframework.cloud:spring-cloud-starter-config</code>. There is also a
|
|
parent pom and BOM (<code class="literal">spring-cloud-starter-parent</code>) for Maven users and a
|
|
Spring IO version management properties file for Gradle and Spring CLI
|
|
users. Example Maven configuration:</p><p><b>pom.xml. </b>
|
|
</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><parent></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.boot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-boot-starter-parent<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>1.3.5.RELEASE<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><relativePath /></span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- lookup parent from repository --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></parent></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>Brixton.RELEASE<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-config<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.boot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-boot-starter-test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><build></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugins></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.boot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-boot-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugins></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></build></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- repositories also needed for snapshots and milestones --></span></pre><p>
|
|
</p><p>Then you can create a standard Spring Boot application, like this simple HTTP server:</p><pre class="screen">@SpringBootApplication
|
|
@RestController
|
|
public class Application {
|
|
|
|
@RequestMapping("/")
|
|
public String home() {
|
|
return "Hello World!";
|
|
}
|
|
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(Application.class, args);
|
|
}
|
|
|
|
}</pre><p>When it runs it will pick up the external configuration from the
|
|
default local config server on port 8888 if it is running. To modify
|
|
the startup behaviour you can change the location of the config server
|
|
using <code class="literal">bootstrap.properties</code> (like <code class="literal">application.properties</code> but for
|
|
the bootstrap phase of an application context), e.g.</p><pre class="screen">spring.cloud.config.uri: http://myconfigserver.com</pre><p>The bootstrap properties will show up in the <code class="literal">/env</code> endpoint as a
|
|
high-priority property source, e.g.</p><pre class="screen">$ curl localhost:8080/env
|
|
{
|
|
"profiles":[],
|
|
"configService:https://github.com/spring-cloud-samples/config-repo/bar.properties":{"foo":"bar"},
|
|
"servletContextInitParams":{},
|
|
"systemProperties":{...},
|
|
...
|
|
}</pre><p>(a property source called "configService:<URL of remote
|
|
repository>/<file name>" contains the property "foo" with value
|
|
"bar" and is highest priority).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the URL in the property source name is the git repository not
|
|
the config server URL.</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_config_server" href="#_spring_cloud_config_server"></a>5. Spring Cloud Config Server</h2></div></div></div><p>The Server provides an HTTP, resource-based API for external
|
|
configuration (name-value pairs, or equivalent YAML content). The
|
|
server is easily embeddable in a Spring Boot application using the
|
|
<code class="literal">@EnableConfigServer</code> annotation. So this app is a config server:</p><p><b>ConfigServer.java. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableConfigServer</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ConfigServer {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(ConfigServer.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
}</pre><p>
|
|
</p><p>Like all Spring Boot apps it runs on port 8080 by default, but you
|
|
can switch it to the conventional port 8888 in various ways. The
|
|
easiest, which also sets a default configuration repository,
|
|
is by launching it with <code class="literal">spring.config.name=configserver</code> (there
|
|
is a <code class="literal">configserver.yml</code> in the Config Server jar). Another is
|
|
to use your own <code class="literal">application.properties</code>, e.g.</p><p><b>application.properties. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">server.port</span>: 8888
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.config.server.git.uri</span>: file://${user.home}/config-repo</pre><p>
|
|
</p><p>where <code class="literal">${user.home}/config-repo</code> is a git repository containing
|
|
YAML and properties files.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>in Windows you need an extra "/" in the file URL if it is
|
|
absolute with a drive prefix, e.g. <code class="literal"><a class="link" href="file:///${user.home}/config-repo" target="_top">file:///${user.home}/config-repo</a></code>.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Here’s a recipe for creating the git repository in the example
|
|
above:</p><pre class="screen">$ cd $HOME
|
|
$ mkdir config-repo
|
|
$ cd config-repo
|
|
$ git init .
|
|
$ echo info.foo: bar > application.properties
|
|
$ git add -A .
|
|
$ git commit -m "Add application.properties"</pre></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>using the local filesystem for your git repository is
|
|
intended for testing only. Use a server to host your
|
|
configuration repositories in production.</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>the initial clone of your configuration repository will
|
|
be quick and efficient if you only keep text files in it. If you start
|
|
to store binary files, especially large ones, you may experience
|
|
delays on the first request for configuration and/or out of memory
|
|
errors in the server.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_environment_repository" href="#_environment_repository"></a>5.1 Environment Repository</h2></div></div></div><p>Where do you want to store the configuration data for the Config
|
|
Server? The strategy that governs this behaviour is the
|
|
<code class="literal">EnvironmentRepository</code>, serving <code class="literal">Environment</code> objects. This
|
|
<code class="literal">Environment</code> is a shallow copy of the domain from the Spring
|
|
<code class="literal">Environment</code> (including <code class="literal">propertySources</code> as the main feature). The
|
|
<code class="literal">Environment</code> resources are parametrized by three variables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">{application}</code> maps to "spring.application.name" on the client side;</li><li class="listitem"><code class="literal">{profile}</code> maps to "spring.profiles.active" on the client (comma separated list); and</li><li class="listitem"><code class="literal">{label}</code> which is a server side feature labelling a "versioned" set of config files.</li></ul></div><p>Repository implementations generally behave just like a Spring Boot
|
|
application loading configuration files from a "spring.config.name"
|
|
equal to the <code class="literal">{application}</code> parameter, and "spring.profiles.active"
|
|
equal to the <code class="literal">{profiles}</code> parameter. Precedence rules for profiles are
|
|
also the same as in a regular Boot application: active profiles take
|
|
precedence over defaults, and if there are multiple profiles the last
|
|
one wins (like adding entries to a <code class="literal">Map</code>).</p><p>Example: a client application has this bootstrap configuration:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> application</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: foo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: dev,mysql</pre><p>
|
|
</p><p>(as usual with a Spring Boot application, these properties could also
|
|
be set as environment variables or command line arguments).</p><p>If the repository is file-based, the server will create an
|
|
<code class="literal">Environment</code> from <code class="literal">application.yml</code> (shared between all clients), and
|
|
<code class="literal">foo.yml</code> (with <code class="literal">foo.yml</code> taking precedence). If the YAML files have
|
|
documents inside them that point to Spring profiles, those are applied
|
|
with higher precedence (in order of the profiles listed), and if
|
|
there are profile-specific YAML (or properties) files these are also
|
|
applied with higher precedence than the defaults. Higher precedence
|
|
translates to a <code class="literal">PropertySource</code> listed earlier in the
|
|
<code class="literal">Environment</code>. (These are the same rules as apply in a standalone
|
|
Spring Boot application.)</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_git_backend" href="#_git_backend"></a>5.1.1 Git Backend</h3></div></div></div><p>The default implementation of <code class="literal">EnvironmentRepository</code> uses a Git
|
|
backend, which is very convenient for managing upgrades and physical
|
|
environments, and also for auditing changes. To change the location of
|
|
the repository you can set the "spring.cloud.config.server.git.uri"
|
|
configuration property in the Config Server (e.g. in
|
|
<code class="literal">application.yml</code>). If you set it with a <code class="literal">file:</code> prefix it should work
|
|
from a local repository so you can get started quickly and easily
|
|
without a server, but in that case the server operates directly on the
|
|
local repository without cloning it (it doesn’t matter if it’s not
|
|
bare because the Config Server never makes changes to the "remote"
|
|
repository). To scale the Config Server up and make it highly
|
|
available, you would need to have all instances of the server pointing
|
|
to the same repository, so only a shared file system would work. Even
|
|
in that case it is better to use the <code class="literal">ssh:</code> protocol for a shared
|
|
filesystem repository, so that the server can clone it and use a local
|
|
working copy as a cache.</p><p>This repository implementation maps the <code class="literal">{label}</code> parameter of the
|
|
HTTP resource to a git label (commit id, branch name or tag). If the
|
|
git branch or tag name contains a slash ("/") then the label in the
|
|
HTTP URL should be specified with the special string "(_)" instead (to
|
|
avoid ambiguity with other URL paths). For example, if the label is
|
|
<code class="literal">foo/bar</code>, replacing the slash would result in a label that looks like
|
|
<code class="literal">foo(_)bar</code>. Be careful with the brackets in
|
|
the URL if you are using a command line client like curl (e.g. escape
|
|
them from the shell with quotes '').</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_placeholders_in_git_uri" href="#_placeholders_in_git_uri"></a>Placeholders in Git URI</h4></div></div></div><p>Spring Cloud Config Server supports a git repository URL with
|
|
placeholders for the <code class="literal">{application}</code> and <code class="literal">{profile}</code> (and <code class="literal">{label}</code> if
|
|
you need it, but remember that the label is applied as a git label
|
|
anyway). So you can easily support a "one repo per application" policy
|
|
using (for example):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/myorg/{application<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>or a "one repo per profile" policy using a similar pattern but with
|
|
<code class="literal">{profile}</code>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_pattern_matching_and_multiple_repositories" href="#_pattern_matching_and_multiple_repositories"></a>Pattern Matching and Multiple Repositories</h4></div></div></div><p>There is also support for more complex requirements with pattern
|
|
matching on the application and profile name. The pattern format is a
|
|
comma-separated list of <code class="literal">{application}/{profile}</code> names with wildcards
|
|
(where a pattern beginning with a wildcard may need to be
|
|
quoted). Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> simple</span>: https://github.com/simple/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> special</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: special*/dev*,*special*/dev*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/special/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> local</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: local*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:/home/configsvc/config-repo</pre><p>If <code class="literal">{application}/{profile}</code> does not match any of the patterns, it
|
|
will use the default uri defined under
|
|
"spring.cloud.config.server.git.uri". In the above example, for the
|
|
"simple" repository, the pattern is <code class="literal">simple/*</code> (i.e. it only matches
|
|
one application named "simple" in all profiles). The "local"
|
|
repository matches all application names beginning with "local" in all
|
|
profiles (the <code class="literal">/*</code> suffix is added automatically to any pattern that
|
|
doesn’t have a profile matcher).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the "one-liner" short cut used in the "simple" example above can
|
|
only be used if the only property to be set is the URI. If you need to
|
|
set anything else (credentials, pattern, etc.) you need to use the full
|
|
form.</p></td></tr></table></div><p>The <code class="literal">pattern</code> property in the repo is actually an array, so you can
|
|
use a YAML array (or <code class="literal">[0]</code>, <code class="literal">[1]</code>, etc. suffixes in properties files)
|
|
to bind to multiple patterns. You may need to do this if you are going
|
|
to run apps with multiple profiles. Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> development</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>:
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/development'</span>
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/staging'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/development/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> staging</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>:
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/qa'</span>
|
|
- <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*/production'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/staging/config-repo</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Spring Cloud will guess that a pattern containing a profile that
|
|
doesn’t end in <code class="literal">*</code> implies that you actually want to match a list of
|
|
profiles starting with this pattern (so <code class="literal">*/staging</code> is a shortcut for
|
|
<code class="literal">["*/staging", "*/staging,*"]</code>). This is common where you need to run
|
|
apps in the "development" profile locally but also the "cloud" profile
|
|
remotely, for instance.</p></td></tr></table></div><p>Every repository can also optionally store config files in
|
|
sub-directories, and patterns to search for those directories can be
|
|
specified as <code class="literal">searchPaths</code>. For example at the top level:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> searchPaths</span>: foo,bar*</pre><p>In this example the server searches for config files in the top level
|
|
and in the "foo/" sub-directory and also any sub-directory whose name
|
|
begins with "bar".</p><p>By default the server clones remote repositories when configuration
|
|
is first requested. The server can be configured to clone the repositories
|
|
at startup. For example at the top level:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/common/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-a</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-a-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloneOnStart</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://git/team-a/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-b</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-b-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloneOnStart</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://git/team-b/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-c</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-c-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://git/team-a/config-repo.git</pre><p>In this example the server clones team-a’s config-repo on startup before it
|
|
accepts any requests. All other repositories will not be cloned until
|
|
configuration from the repository is requested.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Setting a repository to be cloned when the Config Server starts up can
|
|
help to identify a misconfigured configuration source (e.g., an invalid
|
|
repository URI) quickly, while the Config Server is starting up. With
|
|
<code class="literal">cloneOnStart</code> not enabled for a configuration source, the Config Server may
|
|
start successfully with a misconfigured or invalid configuration source and
|
|
not detect an error until an application requests configuration from that
|
|
configuration source.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_authentication" href="#_authentication"></a>Authentication</h4></div></div></div><p>To use HTTP basic authentication on the remote repository add the
|
|
"username" and "password" properties separately (not in the URL),
|
|
e.g.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username</span>: trolley
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: strongpassword</pre><p>If you don’t use HTTPS and user credentials, SSH should also work out
|
|
of the box when you store keys in the default directories (<code class="literal">~/.ssh</code>)
|
|
and the uri points to an SSH location,
|
|
e.g. "<a class="link" href="mailto:git@github.com" target="_top">git@github.com</a>:configuration/cloud-configuration". It is important that an entry for the Git server be present in the <code class="literal">~/.ssh/known_hosts</code> file and that it is in <code class="literal">ssh-rsa</code> format. Other formats (like <code class="literal">ecdsa-sha2-nistp256</code>) are not supported. To avoid surprises, you should ensure that only one entry is present in the <code class="literal">known_hosts</code> file for the Git server and that it is matching with the URL you provided to the config server. If you used a hostname in the URL, you want to have exactly that in the <code class="literal">known_hosts</code> file, not the IP.
|
|
The repository is accessed using JGit, so any documentation you find on
|
|
that should be applicable. HTTPS proxy settings can be set in
|
|
<code class="literal">~/.git/config</code> or in the same way as for any other JVM process via
|
|
system properties (<code class="literal">-Dhttps.proxyHost</code> and <code class="literal">-Dhttps.proxyPort</code>).</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you don’t know where your <code class="literal">~/.git</code> directory is use <code class="literal">git config
|
|
--global</code> to manipulate the settings (e.g. <code class="literal">git config --global
|
|
http.sslVerify false</code>).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_authentication_with_aws_codecommit" href="#_authentication_with_aws_codecommit"></a>Authentication with AWS CodeCommit</h4></div></div></div><p><a class="link" href="http://docs.aws.amazon.com/codecommit/latest/userguide/welcome.html" target="_top">AWS CodeCommit</a> authentication can also be
|
|
done. AWS CodeCommit uses an authentication helper when using Git from the command line. This helper is not
|
|
used with the JGit library, so a JGit CredentialProvider for AWS CodeCommit will be created if the Git
|
|
URI matches the AWS CodeCommit pattern. AWS CodeCommit URIs always look like
|
|
<a class="link" href="https://git-codecommit.${AWS_REGION}.amazonaws.com/${repopath}" target="_top">https://git-codecommit.${AWS_REGION}.amazonaws.com/${repopath}</a>.</p><p>If you provide a username and password with an AWS CodeCommit URI, then these must be
|
|
the <a class="link" href="http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSGettingStartedGuide/AWSCredentials.html" target="_top">AWS accessKeyId and secretAccessKey</a>
|
|
to be used to access the repository. If you do not specify a username and password,
|
|
then the accessKeyId and secretAccessKey will be retrieved using the
|
|
<a class="link" href="http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html" target="_top">AWS Default Credential Provider Chain</a>.</p><p>If your Git URI matches the CodeCommit URI pattern (above) then you must provide
|
|
valid AWS credentials in the username and password, or in one of the locations supported
|
|
by the default credential provider chain. AWS EC2 instances may use
|
|
<a class="link" href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html" target="_top">IAM Roles for EC2 Instances</a>.</p><p>Note: The aws-java-sdk-core jar is an optional dependency. If the aws-java-sdk-core jar is not on your
|
|
classpath, then the AWS Code Commit credential provider will not be created regardless of the git server URI.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_git_ssh_configuration_using_properties" href="#_git_ssh_configuration_using_properties"></a>Git SSH configuration using properties</h4></div></div></div><p>By default, the JGit library used by Spring Cloud Config Server uses SSH configuration files such as <code class="literal">~/.ssh/known_hosts</code> and <code class="literal">/etc/ssh/ssh_config</code> when connecting to Git repositories using an SSH URI.
|
|
In cloud environments such as Cloud Foundry, the local filesystem may be ephemeral or not easily accessible. For cases such as these, SSH configuration can be set using
|
|
Java properties. In order to activate property based SSH configuration, the property <code class="literal">spring.cloud.config.server.git.ignoreLocalSshSettings</code> must be set to <code class="literal">true</code>.
|
|
Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: git<em><span class="hl-annotation" style="color: gray">@gitserver.com:team/repo1.git</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ignoreLocalSshSettings</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> hostKey</span>: someHostKey
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> hostKeyAlgorithm</span>: ssh-rsa
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> privateKey</span>: |
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
MIIEpgIBAAKCAQEAx4UbaDzY5xjW6hc9jwN0mX33XpTDVW9WqHp5AKaRbtAC3DqX
|
|
IXFMPgw3K45jxRb93f8tv9vL3rD9CUG1Gv4FM+o7ds7FRES5RTjv2RT/JVNJCoqF
|
|
ol8+ngLqRZCyBtQN7zYByWMRirPGoDUqdPYrj2yq+ObBBNhg5N+hOwKjjpzdj2Ud
|
|
<span class="hl-number">1l</span>7R+wxIqmJo1IYyy16xS8WsjyQuyC0lL456qkd5BDZ0Ag8j2X9H9D5220Ln7s9i
|
|
oezTipXipS7p7Jekf3Ywx6abJwOmB0rX79dV4qiNcGgzATnG1PkXxqt76VhcGa0W
|
|
DDVHEEYGbSQ6hIGSh0I7BQun0aLRZojfE3gqHQIDAQABAoIBAQCZmGrk8BK6tXCd
|
|
fY6yTiKxFzwb38IQP0ojIUWNrq0+<span class="hl-number">9</span>Xt+NsypviLHkXfXXCKKU4zUHeIGVRq5MN9b
|
|
BO56/RrcQHHOoJdUWuOV2qMqJvPUtC0CpGkD+valhfD75MxoXU7s3FK7yjxy3rsG
|
|
EmfA6tHV8/<span class="hl-number">4</span>a5umo5TqSd2YTm5B19AhRqiuUVI1wTB41DjULUGiMYrnYrhzQlVvj
|
|
<span class="hl-number">5</span>MjnKTlYu3V8PoYDfv1GmxPPh6vlpafXEeEYN8VB97e5x3DGHjZ5UrurAmTLTdO8
|
|
+AahyoKsIY612TkkQthJlt7FJAwnCGMgY6podzzvzICLFmmTXYiZ/<span class="hl-number">28</span>I4BX/mOSe
|
|
pZVnfRixAoGBAO6Uiwt40/PKs53mCEWngslSCsh9oGAaLTf/XdvMns5VmuyyAyKG
|
|
ti8Ol5wqBMi4GIUzjbgUvSUt+IowIrG3f5tN85wpjQ1UGVcpTnl5Qo9xaS1PFScQ
|
|
xrtWZ9eNj2TsIAMp/svJsyGG3OibxfnuAIpSXNQiJPwRlW3irzpGgVx/AoGBANYW
|
|
dnhshUcEHMJi3aXwR12OTDnaLoanVGLwLnkqLSYUZA7ZegpKq90UAuBdcEfgdpyi
|
|
PhKpeaeIiAaNnFo8m9aoTKr+<span class="hl-number">7</span>I6/uMTlwrVnfrsVTZv3orxjwQV20YIBCVRKD1uX
|
|
VhE0ozPZxwwKSPAFocpyWpGHGreGF1AIYBE9UBtjAoGBAI8bfPgJpyFyMiGBjO6z
|
|
FwlJc/xlFqDusrcHL7abW5qq0L4v3R+FrJw3ZYufzLTVcKfdj6GelwJJO+<span class="hl-number">8</span>wBm+R
|
|
gTKYJItEhT48duLIfTDyIpHGVm9+I1MGhh5zKuCqIhxIYr9jHloBB7kRm0rPvYY4
|
|
VAykcNgyDvtAVODP+<span class="hl-number">4</span>m6JvhjAoGBALbtTqErKN47V0+JJpapLnF0KxGrqeGIjIRV
|
|
cYA6V4WYGr7NeIfesecfOC356PyhgPfpcVyEztwlvwTKb3RzIT1TZN8fH4YBr6Ee
|
|
KTbTjefRFhVUjQqnucAvfGi29f+<span class="hl-number">9</span>oE3Ei9f7wA+H35ocF6JvTYUsHNMIO/<span class="hl-number">3</span>gZ38N
|
|
CPjyCMa9AoGBAMhsITNe3QcbsXAbdUR00dDsIFVROzyFJ2m40i4KCRM35bC/BIBs
|
|
q0TY3we+ERB40U8Z2BvU61QuwaunJ2+uGadHo58VSVdggqAo0BSkH58innKKt96J
|
|
<span class="hl-number">69</span>pcVH/<span class="hl-number">4</span>rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
|
|
-----END RSA PRIVATE KEY-----</pre><div class="table"><a name="d0e1289" href="#d0e1289"></a><p class="title"><b>Table 5.1. SSH Configuration properties</b></p><div class="table-contents"><table summary="SSH Configuration properties" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Property Name</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Remarks</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>ignoreLocalSshSettings</strong></span></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>If true, use property based SSH config instead of file based. Must be set at as <code class="literal">spring.cloud.config.server.git.ignoreLocalSshSettings</code>, <span class="strong"><strong>not</strong></span> inside a repository definition.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>privateKey</strong></span></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Valid SSH private key. Must be set if <code class="literal">ignoreLocalSshSettings</code> is true and Git URI is SSH format</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>hostKey</strong></span></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Valid SSH host key. Must be set if <code class="literal">hostKeyAlgorithm</code> is also set</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>hostKeyAlgorithm</strong></span></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>One of <code class="literal">ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384 ,ecdsa-sha2-nistp521</code>. Must be set if <code class="literal">hostKey</code> is also set</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p><span class="strong"><strong>strictHostKeyChecking</strong></span></p></td><td style="" align="left" valign="top"><p><code class="literal">true</code> or <code class="literal">false</code>. If false, ignore errors with host key</p></td></tr></tbody></table></div></div><br class="table-break"></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_placeholders_in_git_search_paths" href="#_placeholders_in_git_search_paths"></a>Placeholders in Git Search Paths</h4></div></div></div><p>Spring Cloud Config Server also supports a search path with
|
|
placeholders for the <code class="literal">{application}</code> and <code class="literal">{profile}</code> (and <code class="literal">{label}</code> if
|
|
you need it). Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> searchPaths</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{application}'</span></pre><p>searches the repository for files in the same name as the directory
|
|
(as well as the top level). Wildcards are also valid in a search
|
|
path with placeholders (any matching directory is included in the
|
|
search).</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_force_pull_in_git_repositories" href="#_force_pull_in_git_repositories"></a>Force pull in Git Repositories</h4></div></div></div><p>As mentioned before Spring Cloud Config Server makes a clone of the
|
|
remote git repository and if somehow the local copy gets dirty (e.g.
|
|
folder content changes by OS process) so Spring Cloud Config Server
|
|
cannot update the local copy from remote repository.</p><p>To solve this there is a <code class="literal">force-pull</code> property that will make Spring Cloud
|
|
Config Server force pull from remote repository if the local copy is dirty.
|
|
Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://github.com/spring-cloud-samples/config-repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre><p>If you have a multiple repositories configuration you can configure the
|
|
<code class="literal">force-pull</code> property per repository. Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://git/common/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repos</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-a</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-a-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://git/team-a/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-b</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-b-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://git/team-b/config-repo.git
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> force-pull</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> team-c</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> pattern</span>: team-c-*
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: http://git/team-a/config-repo.git</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The default value for <code class="literal">force-pull</code> property is <code class="literal">false</code>.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_version_control_backend_filesystem_use" href="#_version_control_backend_filesystem_use"></a>5.1.2 Version Control Backend Filesystem Use</h3></div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>With VCS based backends (git, svn) files are checked out or cloned to the local filesystem. By default they are put in the system temporary directory with a prefix of <code class="literal">config-repo-</code>. On linux, for example it could be <code class="literal">/tmp/config-repo-<randomid></code>. Some operating systems <a class="link" href="http://serverfault.com/questions/377348/when-does-tmp-get-cleared/377349#377349" target="_top">routinely clean out</a> temporary directories. This can lead to unexpected behaviour such as missing properties. To avoid this problem, change the directory Config Server uses, by setting <code class="literal">spring.cloud.config.server.git.basedir</code> or <code class="literal">spring.cloud.config.server.svn.basedir</code> to a directory that does not reside in the system temp structure.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_file_system_backend" href="#_file_system_backend"></a>5.1.3 File System Backend</h3></div></div></div><p>There is also a "native" profile in the Config Server that doesn’t use
|
|
Git, but just loads the config files from the local classpath or file
|
|
system (any static URL you want to point to with
|
|
"spring.cloud.config.server.native.searchLocations"). To use the
|
|
native profile just launch the Config Server with
|
|
"spring.profiles.active=native".</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Remember to use the <code class="literal">file:</code> prefix for file resources (the
|
|
default without a prefix is usually the classpath). Just as with any
|
|
Spring Boot configuration you can embed <code class="literal">${}</code>-style environment
|
|
placeholders, but remember that absolute paths in Windows require an
|
|
extra "/", e.g. <code class="literal"><a class="link" href="file:///${user.home}/config-repo" target="_top">file:///${user.home}/config-repo</a></code></p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>The default value of the <code class="literal">searchLocations</code> is identical to a
|
|
local Spring Boot application (so <code class="literal">[classpath:/, classpath:/config,
|
|
file:./, file:./config]</code>). This does not expose the
|
|
<code class="literal">application.properties</code> from the server to all clients because any
|
|
property sources present in the server are removed before being sent
|
|
to the client.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>A filesystem backend is great for getting started quickly and
|
|
for testing. To use it in production you need to be sure that the
|
|
file system is reliable, and shared across all instances of the
|
|
Config Server.</p></td></tr></table></div><p>The search locations can contain placeholders for <code class="literal">{application}</code>,
|
|
<code class="literal">{profile}</code> and <code class="literal">{label}</code>. In this way you can segregate the
|
|
directories in the path, and choose a strategy that makes sense for
|
|
you (e.g. sub-directory per application, or sub-directory per
|
|
profile).</p><p>If you don’t use placeholders in the search locations, this repository
|
|
also appends the <code class="literal">{label}</code> parameter of the HTTP resource to a suffix
|
|
on the search path, so properties files are loaded from each search
|
|
location <span class="strong"><strong>and</strong></span> a subdirectory with the same name as the label (the
|
|
labelled properties take precedence in the Spring Environment). Thus
|
|
the default behaviour with no placeholders is the same as adding a
|
|
search location ending with <code class="literal">/{label}/</code>. For example <code class="literal">file:/tmp/config</code>
|
|
is the same as <code class="literal">file:/tmp/config,file:/tmp/config/{label}</code>. This behavior can be
|
|
disabled by setting <code class="literal">spring.cloud.config.server.native.addLabelLocations=false</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_vault_backend" href="#_vault_backend"></a>5.1.4 Vault Backend</h3></div></div></div><p>Spring Cloud Config Server also supports <a class="link" href="https://www.vaultproject.io" target="_top">Vault</a> as a backend.</p><div class="sidebar"><div class="titlepage"></div><p>Vault is a tool for securely accessing secrets. A secret is anything
|
|
that you want to tightly control access to, such as API keys, passwords,
|
|
certificates, and more. Vault provides a unified interface to any secret,
|
|
while providing tight access control and recording a detailed audit log.</p></div><p>For more information on Vault see the <a class="link" href="https://www.vaultproject.io/intro/index.html" target="_top">Vault quickstart guide</a>.</p><p>To enable the config server to use a Vault backend you must run your config server
|
|
with the <code class="literal">vault</code> profile. For example in your config server’s <code class="literal">application.properties</code>
|
|
you can add <code class="literal">spring.profiles.active=vault</code>.</p><p>By default the config server will assume your Vault server is running at
|
|
<code class="literal"><a class="link" href="http://127.0.0.1:8200" target="_top">http://127.0.0.1:8200</a></code>. It also will assume that the name of backend
|
|
is <code class="literal">secret</code> and the key is <code class="literal">application</code>. All of these defaults can be
|
|
configured in your config server’s <code class="literal">application.properties</code>. Below is a
|
|
table of configurable Vault properties. All properties are prefixed with
|
|
<code class="literal">spring.cloud.config.server.vault</code>.</p><div class="informaltable"><table style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Name</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Default Value</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>host</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>127.0.0.1</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>port</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>8200</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>scheme</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>backend</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>secret</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>defaultKey</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>profileSeparator</p></td><td style="" align="left" valign="top"><p>,</p></td></tr></tbody></table></div><p>All configurable properties can be found in
|
|
<code class="literal">org.springframework.cloud.config.server.environment.VaultEnvironmentRepository</code>.</p><p>With your config server running you can make HTTP requests to the server to retrieve
|
|
values from the Vault backend. To do this you will need a token for your Vault server.</p><p>First place some data in you Vault. For example</p><pre class="programlisting">$ vault write secret/application foo=bar baz=bam
|
|
$ vault write secret/myapp foo=myappsbar</pre><p>Now make the HTTP request to your config server to retrieve the values.</p><p><code class="literal">$ curl -X "GET" "http://localhost:8888/myapp/default" -H "X-Config-Token: yourtoken"</code></p><p>You should see a response similar to this after making the above request.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"myapp"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"profiles"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"default"</span>
|
|
]<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"label"</span>:null<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"version"</span>:null<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"state"</span>:null<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"propertySources"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"vault:myapp"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"source"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"myappsbar"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"vault:application"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"source"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"baz"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bam"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_multiple_properties_sources" href="#_multiple_properties_sources"></a>Multiple Properties Sources</h4></div></div></div><p>When using Vault you can provide your applications with multiple properties sources.
|
|
For example, assume you have written data to the following paths in Vault.</p><pre class="programlisting">secret/myApp,dev
|
|
secret/myApp
|
|
secret/application,dev
|
|
secret/application</pre><p>Properties written to <code class="literal">secret/application</code> are available to
|
|
<a class="link" href="#_vault_server" title="Vault Server">all applications using the Config Server</a>. An
|
|
application with the name <code class="literal">myApp</code> would have any properties
|
|
written to <code class="literal">secret/myApp</code> and <code class="literal">secret/application</code> available to it.
|
|
When <code class="literal">myApp</code> has the <code class="literal">dev</code> profile enabled then properties written to
|
|
all of the above paths would be available to it, with properties in
|
|
the first path in the list taking priority over the others.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sharing_configuration_with_all_applications" href="#_sharing_configuration_with_all_applications"></a>5.1.5 Sharing Configuration With All Applications</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_file_based_repositories" href="#_file_based_repositories"></a>File Based Repositories</h4></div></div></div><p>With file-based (i.e. git, svn and native) repositories, resources
|
|
with file names in <code class="literal">application*</code> are shared between all client
|
|
applications (so <code class="literal">application.properties</code>, <code class="literal">application.yml</code>,
|
|
<code class="literal">application-*.properties</code> etc.). You can use resources with these
|
|
file names to configure global defaults and have them overridden by
|
|
application-specific files as necessary.</p><p>The #_property_overrides[property overrides] feature can also be used
|
|
for setting global defaults, and with placeholders applications are
|
|
allowed to override them locally.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>With the "native" profile (local file system backend) it is
|
|
recommended that you use an explicit search location that isn’t part
|
|
of the server’s own configuration. Otherwise the <code class="literal">application*</code>
|
|
resources in the default search locations are removed because they are
|
|
part of the server.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_vault_server" href="#_vault_server"></a>Vault Server</h4></div></div></div><p>When using Vault as a backend you can share configuration with
|
|
all applications by placing configuration in
|
|
<code class="literal">secret/application</code>. For example, if you run this Vault command</p><pre class="programlisting">$ vault write secret/application foo=bar baz=bam</pre><p>All applications using the config server will have the properties
|
|
<code class="literal">foo</code> and <code class="literal">baz</code> available to them.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_composite_environment_repositories" href="#_composite_environment_repositories"></a>5.1.6 Composite Environment Repositories</h3></div></div></div><p>In some scenarios you may wish to pull configuration data from multiple
|
|
environment repositories. To do this just enable
|
|
multiple profiles in your config server’s application properties or YAML file.
|
|
If, for example, you want to pull configuration data from a Git repository
|
|
as well as a SVN repository you would set the following properties for your
|
|
configuration server.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> active</span>: git<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span> svn
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> svn</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:///path/to/svn/repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> order</span>: <span class="hl-number">2</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> git</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: file:///path/to/git/repo
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> order</span>: <span class="hl-number">1</span></pre><p>In addition to each repo specifying a URI, you can also specify an <code class="literal">order</code> property.
|
|
The <code class="literal">order</code> property allows you to specify the priority order for all your repositories.
|
|
The lower the numerical value of the <code class="literal">order</code> property the higher priority it will have.
|
|
The priority order of a repository will help resolve any potential conflicts between
|
|
repositories that contain values for the same properties.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Any type of failure when retrieving values from an environment repositoy
|
|
will result in a failure for the entire composite environment.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When using a composite environment it is important that all repos contain
|
|
the same label(s). If you have an environment similar to the one above and you request
|
|
configuration data with the label <code class="literal">master</code> but the SVN
|
|
repo does not contain a branch called <code class="literal">master</code> the entire request will fail.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_custom_composite_environment_repositories" href="#_custom_composite_environment_repositories"></a>Custom Composite Environment Repositories</h4></div></div></div><p>It is also possible to provide your own <code class="literal">EnvironmentRepository</code> bean
|
|
to be included as part of a composite environment in addition to
|
|
using one of the environment repositories from Spring Cloud. To do this your bean
|
|
must implement the <code class="literal">EnvironmentRepository</code> interface. If you would like to control
|
|
the priority of you custom <code class="literal">EnvironmentRepository</code> within the composite
|
|
environment you should also implement the <code class="literal">Ordered</code> interface and override the
|
|
<code class="literal">getOrdered</code> method. If you do not implement the <code class="literal">Ordered</code> interface then your
|
|
<code class="literal">EnvironmentRepository</code> will be given the lowest priority.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_property_overrides" href="#_property_overrides"></a>5.1.7 Property Overrides</h3></div></div></div><p>The Config Server has an "overrides" feature that allows the operator
|
|
to provide configuration properties to all applications that cannot be
|
|
accidentally changed by the application using the normal Spring Boot
|
|
hooks. To declare overrides just add a map of name-value pairs to
|
|
<code class="literal">spring.cloud.config.server.overrides</code>. For example</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> overrides</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> foo</span>: bar</pre><p>will cause all applications that are config clients to read <code class="literal">foo=bar</code>
|
|
independent of their own configuration. (Of course an application can
|
|
use the data in the Config Server in any way it likes, so overrides
|
|
are not enforceable, but they do provide useful default behaviour if
|
|
they are Spring Cloud Config clients.)</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Normal, Spring environment placeholders with "${}" can be escaped
|
|
(and resolved on the client) by using backslash ("\") to escape the
|
|
"$" or the "{", e.g. <code class="literal">\${app.foo:bar}</code> resolves to "bar" unless the
|
|
app provides its own "app.foo". Note that in YAML you don’t need to
|
|
escape the backslash itself, but in properties files you do, when you
|
|
configure the overrides on the server.</p></td></tr></table></div><p>You can change the priority of all overrides in the client to be more
|
|
like default values, allowing applications to supply their own values
|
|
in environment variables or System properties, by setting the flag
|
|
<code class="literal">spring.cloud.config.overrideNone=true</code> (default is false) in the
|
|
remote repository.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_health_indicator" href="#_health_indicator"></a>5.2 Health Indicator</h2></div></div></div><p>Config Server comes with a Health Indicator that checks if the configured
|
|
<code class="literal">EnvironmentRepository</code> is working. By default it asks the <code class="literal">EnvironmentRepository</code>
|
|
for an application named <code class="literal">app</code>, the <code class="literal">default</code> profile and the default
|
|
label provided by the <code class="literal">EnvironmentRepository</code> implementation.</p><p>You can configure the Health Indicator to check more applications
|
|
along with custom profiles and custom labels, e.g.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> health</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repositories</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> myservice</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> label</span>: mylabel
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> myservice-dev</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: myservice
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>: development</pre><p>You can disable the Health Indicator by setting <code class="literal">spring.cloud.config.server.health.enabled=false</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_security" href="#_security"></a>5.3 Security</h2></div></div></div><p>You are free to secure your Config Server in any way that makes sense
|
|
to you (from physical network security to OAuth2 bearer
|
|
tokens), and Spring Security and Spring Boot make it easy to do pretty
|
|
much anything.</p><p>To use the default Spring Boot configured HTTP Basic security, just
|
|
include Spring Security on the classpath (e.g. through
|
|
<code class="literal">spring-boot-starter-security</code>). The default is a username of "user"
|
|
and a randomly generated password, which isn’t going to be very useful
|
|
in practice, so we recommend you configure the password (via
|
|
<code class="literal">security.user.password</code>) and encrypt it (see below for instructions
|
|
on how to do that).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_encryption_and_decryption_2" href="#_encryption_and_decryption_2"></a>5.4 Encryption and Decryption</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p><span class="strong"><strong>Prerequisites:</strong></span> to use the encryption and decryption features
|
|
you need the full-strength JCE installed in your JVM (it’s not there by default).
|
|
You can download the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files"
|
|
from Oracle, and follow instructions for installation (essentially replace the 2 policy files
|
|
in the JRE lib/security directory with the ones that you downloaded).</p></td></tr></table></div><p>If the remote property sources contain encrypted content (values
|
|
starting with <code class="literal">{cipher}</code>) they will be decrypted before sending to
|
|
clients over HTTP. The main advantage of this set up is that the
|
|
property values don’t have to be in plain text when they are "at rest"
|
|
(e.g. in a git repository). If a value cannot be decrypted it is
|
|
removed from the property source and an additional property is added
|
|
with the same key, but prefixed with "invalid." and a value that means
|
|
"not applicable" (usually "<n/a>"). This is largely to prevent cipher
|
|
text being used as a password and accidentally leaking.</p><p>If you are setting up a remote config repository for config client
|
|
applications it might contain an <code class="literal">application.yml</code> like this, for
|
|
instance:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> datasource</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username</span>: dbuser
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ'</span></pre><p>
|
|
</p><p>Encrypted values in a .properties file must not be wrapped in quotes, otherwise the value will not be decrypted:</p><p><b>application.properties. </b>
|
|
</p><pre class="screen">spring.datasource.username: dbuser
|
|
spring.datasource.password: {cipher}FKSAJDFGYOS8F7GLHAKERGFHLSAJ</pre><p>
|
|
</p><p>You can safely push this plain text to a shared git repository and the
|
|
secret password is protected.</p><p>The server also exposes <code class="literal">/encrypt</code> and <code class="literal">/decrypt</code> endpoints (on the
|
|
assumption that these will be secured and only accessed by authorized
|
|
agents). If you are editing a remote config file you can use the Config Server
|
|
to encrypt values by POSTing to the <code class="literal">/encrypt</code> endpoint, e.g.</p><pre class="screen">$ curl localhost:8888/encrypt -d mysecret
|
|
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If the value you are encrypting has characters in it that need to be URL encoded you should use
|
|
the <code class="literal">--data-urlencode</code> option to <code class="literal">curl</code> to make sure they are encoded properly.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Be sure not to include any of the curl command statistics in the encrypted value.
|
|
Outputting the value to a file can help avoid this problem.</p></td></tr></table></div><p>The inverse operation is also available via <code class="literal">/decrypt</code> (provided the server is
|
|
configured with a symmetric key or a full key pair):</p><pre class="screen">$ curl localhost:8888/decrypt -d 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
mysecret</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you are testing like this with curl, then use
|
|
<code class="literal">--data-urlencode</code> (instead of <code class="literal">-d</code>) or set an explicit <code class="literal">Content-Type:
|
|
text/plain</code> to make sure curl encodes the data correctly when there
|
|
are special characters ('+' is particularly tricky).</p></td></tr></table></div><p>Take the encrypted value and add the <code class="literal">{cipher}</code> prefix before you put
|
|
it in the YAML or properties file, and before you commit and push it
|
|
to a remote, potentially insecure store.</p><p>The <code class="literal">/encrypt</code> and <code class="literal">/decrypt</code> endpoints also both accept paths of the
|
|
form <code class="literal">/*/{name}/{profiles}</code> which can be used to control cryptography
|
|
per application (name) and profile when clients call into the main
|
|
Environment resource.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>to control the cryptography in this granular way you must also
|
|
provide a <code class="literal">@Bean</code> of type <code class="literal">TextEncryptorLocator</code> that creates a
|
|
different encryptor per name and profiles. The one that is provided
|
|
by default does not do this (so all encryptions use the same key).</p></td></tr></table></div><p>The <code class="literal">spring</code> command line client (with Spring Cloud CLI extensions
|
|
installed) can also be used to encrypt and decrypt, e.g.</p><pre class="screen">$ spring encrypt mysecret --key foo
|
|
682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
$ spring decrypt --key foo 682bc583f4641835fa2db009355293665d2647dade3375c0ee201de2a49f7bda
|
|
mysecret</pre><p>To use a key in a file (e.g. an RSA public key for encryption) prepend
|
|
the key value with "@" and provide the file path, e.g.</p><pre class="screen">$ spring encrypt mysecret --key @${HOME}/.ssh/id_rsa.pub
|
|
AQAjPgt3eFZQXwt8tsHAVv/QHiY5sI2dRcR+...</pre><p>The key argument is mandatory (despite having a <code class="literal">--</code> prefix).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_key_management" href="#_key_management"></a>5.5 Key Management</h2></div></div></div><p>The Config Server can use a symmetric (shared) key or an asymmetric
|
|
one (RSA key pair). The asymmetric choice is superior in terms of
|
|
security, but it is often more convenient to use a symmetric key since
|
|
it is just a single property value to configure.</p><p>To configure a symmetric key you just need to set <code class="literal">encrypt.key</code> to a
|
|
secret String (or use an enviroment variable <code class="literal">ENCRYPT_KEY</code> to keep it
|
|
out of plain text configuration files).</p><p>To configure an asymmetric key you can either set the key as a
|
|
PEM-encoded text value (in <code class="literal">encrypt.key</code>), or via a keystore (e.g. as
|
|
created by the <code class="literal">keytool</code> utility that comes with the JDK). The
|
|
keystore properties are <code class="literal">encrypt.keyStore.*</code> with <code class="literal">*</code> equal to</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">location</code> (a <code class="literal">Resource</code> location),</li><li class="listitem"><code class="literal">password</code> (to unlock the keystore) and</li><li class="listitem"><code class="literal">alias</code> (to identify which key in the store is to be
|
|
used).</li></ul></div><p>The encryption is done with the public key, and a private key is
|
|
needed for decryption. Thus in principle you can configure only the
|
|
public key in the server if you only want to do encryption (and are
|
|
prepared to decrypt the values yourself locally with the private
|
|
key). In practice you might not want to do that because it spreads the
|
|
key management process around all the clients, instead of
|
|
concentrating it in the server. On the other hand it’s a useful option
|
|
if your config server really is relatively insecure and only a
|
|
handful of clients need the encrypted properties.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_creating_a_key_store_for_testing" href="#_creating_a_key_store_for_testing"></a>5.6 Creating a Key Store for Testing</h2></div></div></div><p>To create a keystore for testing you can do something like this:</p><pre class="screen">$ keytool -genkeypair -alias mytestkey -keyalg RSA \
|
|
-dname "CN=Web Server,OU=Unit,O=Organization,L=City,S=State,C=US" \
|
|
-keypass changeme -keystore server.jks -storepass letmein</pre><p>Put the <code class="literal">server.jks</code> file in the classpath (for instance) and then in
|
|
your <code class="literal">application.yml</code> for the Config Server:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">encrypt</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> keyStore</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> location</span>: classpath:/server.jks
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: letmein
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> alias</span>: mytestkey
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> secret</span>: changeme</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_multiple_keys_and_key_rotation" href="#_using_multiple_keys_and_key_rotation"></a>5.7 Using Multiple Keys and Key Rotation</h2></div></div></div><p>In addition to the <code class="literal">{cipher}</code> prefix in encrypted property values, the
|
|
Config Server looks for <code class="literal">{name:value}</code> prefixes (zero or many) before
|
|
the start of the (Base64 encoded) cipher text. The keys are passed to
|
|
a <code class="literal">TextEncryptorLocator</code> which can do whatever logic it needs to
|
|
locate a <code class="literal">TextEncryptor</code> for the cipher. If you have configured a
|
|
keystore (<code class="literal">encrypt.keystore.location</code>) the default locator will look
|
|
for keys in the store with aliases as supplied by the "key" prefix,
|
|
i.e. with a cipher text like this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">foo</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> bar</span>: `{cipher}{key:testkey}...`</pre><p>the locator will look for a key named "testkey". A secret can also be
|
|
supplied via a <code class="literal">{secret:…​}</code> value in the prefix, but if it is not
|
|
the default is to use the keystore password (which is what you get
|
|
when you build a keytore and don’t specify a secret). If you <span class="strong"><strong>do</strong></span>
|
|
supply a secret it is recommended that you also encrypt the secrets
|
|
using a custom <code class="literal">SecretLocator</code>.</p><p>Key rotation is hardly ever necessary on cryptographic grounds if the
|
|
keys are only being used to encrypt a few bytes of configuration data
|
|
(i.e. they are not being used elsewhere), but occasionally you might
|
|
need to change the keys if there is a security breach for instance. In
|
|
that case all the clients would need to change their source config
|
|
files (e.g. in git) and use a new <code class="literal">{key:…​}</code> prefix in all the
|
|
ciphers, checking beforehand of course that the key alias is available
|
|
in the Config Server keystore.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>the <code class="literal">{name:value}</code> prefixes can also be added to plaintext posted
|
|
to the <code class="literal">/encrypt</code> endpoint, if you want to let the Config Server
|
|
handle all encryption as well as decryption.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_serving_encrypted_properties" href="#_serving_encrypted_properties"></a>5.8 Serving Encrypted Properties</h2></div></div></div><p>Sometimes you want the clients to decrypt the configuration locally,
|
|
instead of doing it in the server. In that case you can still have
|
|
/encrypt and /decrypt endpoints (if you provide the <code class="literal">encrypt.*</code>
|
|
configuration to locate a key), but you need to explicitly switch off
|
|
the decryption of outgoing properties using
|
|
<code class="literal">spring.cloud.config.server.encrypt.enabled=false</code>. If you don’t care
|
|
about the endpoints, then it should work if you configure neither the
|
|
key nor the enabled flag.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_serving_alternative_formats" href="#_serving_alternative_formats"></a>6. Serving Alternative Formats</h2></div></div></div><p>The default JSON format from the environment endpoints is perfect for
|
|
consumption by Spring applications because it maps directly onto the
|
|
<code class="literal">Environment</code> abstraction. If you prefer you can consume the same data
|
|
as YAML or Java properties by adding a suffix to the resource path
|
|
(".yml", ".yaml" or ".properties"). This can be useful for consumption
|
|
by applications that do not care about the structure of the JSON
|
|
endpoints, or the extra metadata they provide, for example an
|
|
application that is not using Spring might benefit from the simplicity
|
|
of this approach.</p><p>The YAML and properties representations have an additional flag
|
|
(provided as a boolean query parameter <code class="literal">resolvePlaceholders</code>) to
|
|
signal that placeholders in the source documents, in the standard
|
|
Spring <code class="literal">${…​}</code> form, should be resolved in the output where possible
|
|
before rendering. This is a useful feature for consumers that don’t
|
|
know about the Spring placeholder conventions.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>there are limitations in using the YAML or properties formats,
|
|
mainly in relation to the loss of metadata. The JSON is structured as
|
|
an ordered list of property sources, for example, with names that
|
|
correlate with the source. The YAML and properties forms are coalesced
|
|
into a single map, even if the origin of the values has multiple
|
|
sources, and the names of the original source files are lost. The YAML
|
|
representation is not necessarily a faithful representation of the
|
|
YAML source in a backing repository either: it is constructed from a
|
|
list of flat property sources, and assumptions have to be made about
|
|
the form of the keys.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_serving_plain_text" href="#_serving_plain_text"></a>7. Serving Plain Text</h2></div></div></div><p>Instead of using the <code class="literal">Environment</code> abstraction (or one of the
|
|
alternative representations of it in YAML or properties format) your
|
|
applications might need generic plain text configuration files,
|
|
tailored to their environment. The Config Server provides these
|
|
through an additional endpoint at <code class="literal">/{name}/{profile}/{label}/{path}</code>
|
|
where "name", "profile" and "label" have the same meaning as the
|
|
regular environment endpoint, but "path" is a file name
|
|
(e.g. <code class="literal">log.xml</code>). The source files for this endpoint are located in
|
|
the same way as for the environment endpoints: the same search path is
|
|
used as for properties or YAML files, but instead of aggregating all
|
|
matching resources, only the first one to match is returned.</p><p>After a resource is located, placeholders in the normal format
|
|
(<code class="literal">${…​}</code>) are resolved using the effective <code class="literal">Environment</code> for the
|
|
application name, profile and label supplied. In this way the resource
|
|
endpoint is tightly integrated with the environment
|
|
endpoints. Example, if you have this layout for a GIT (or SVN)
|
|
repository:</p><pre class="screen">application.yml
|
|
nginx.conf</pre><p>where <code class="literal">nginx.conf</code> looks like this:</p><pre class="screen">server {
|
|
listen 80;
|
|
server_name ${nginx.server.name};
|
|
}</pre><p>and <code class="literal">application.yml</code> like this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">nginx</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: example.com
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">---</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profiles</span>: development
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">nginx</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: develop.com</pre><p>then the <code class="literal">/foo/default/master/nginx.conf</code> resource looks like this:</p><pre class="screen">server {
|
|
listen 80;
|
|
server_name example.com;
|
|
}</pre><p>and <code class="literal">/foo/development/master/nginx.conf</code> like this:</p><pre class="screen">server {
|
|
listen 80;
|
|
server_name develop.com;
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>just like the source files for environment configuration, the
|
|
"profile" is used to resolve the file name, so if you want a
|
|
profile-specific file then <code class="literal">/*/development/*/logback.xml</code> will be
|
|
resolved by a file called <code class="literal">logback-development.xml</code> (in preference
|
|
to <code class="literal">logback.xml</code>).</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_embedding_the_config_server" href="#_embedding_the_config_server"></a>8. Embedding the Config Server</h2></div></div></div><p>The Config Server runs best as a standalone application, but if you
|
|
need to you can embed it in another application. Just use the
|
|
<code class="literal">@EnableConfigServer</code> annotation. An optional property that can be
|
|
useful in this case is <code class="literal">spring.cloud.config.server.bootstrap</code> which is
|
|
a flag to indicate that the server should configure itself from its
|
|
own remote repository. The flag is off by default because it can delay
|
|
startup, but when embedded in another application it makes sense to
|
|
initialize the same way as any other application.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>It should be obvious, but remember that if you use the bootstrap
|
|
flag the config server will need to have its name and repository URI
|
|
configured in <code class="literal">bootstrap.yml</code>.</p></td></tr></table></div><p>To change the location of the server endpoints you can (optionally)
|
|
set <code class="literal">spring.cloud.config.server.prefix</code>, e.g. "/config", to serve the
|
|
resources under a prefix. The prefix should start but not end with a
|
|
"/". It is applied to the <code class="literal">@RequestMappings</code> in the Config Server
|
|
(i.e. underneath the Spring Boot prefixes <code class="literal">server.servletPath</code> and
|
|
<code class="literal">server.contextPath</code>).</p><p>If you want to read the configuration for an application directly from
|
|
the backend repository (instead of from the config server) that’s
|
|
basically an embedded config server with no endpoints. You can switch
|
|
off the endpoints entirely if you don’t use the <code class="literal">@EnableConfigServer</code>
|
|
annotation (just set <code class="literal">spring.cloud.config.server.bootstrap=true</code>).</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_push_notifications_and_spring_cloud_bus" href="#_push_notifications_and_spring_cloud_bus"></a>9. Push Notifications and Spring Cloud Bus</h2></div></div></div><p>Many source code repository providers (like Github, Gitlab or Bitbucket
|
|
for instance) will notify you of changes in a repository through a
|
|
webhook. You can configure the webhook via the provider’s user
|
|
interface as a URL and a set of events in which you are
|
|
interested. For instance
|
|
<a class="link" href="https://developer.github.com/v3/activity/events/types/#pushevent" target="_top">Github</a>
|
|
will POST to the webhook with a JSON body containing a list of
|
|
commits, and a header "X-Github-Event" equal to "push". If you add a
|
|
dependency on the <code class="literal">spring-cloud-config-monitor</code> library and activate
|
|
the Spring Cloud Bus in your Config Server, then a "/monitor" endpoint
|
|
is enabled.</p><p>When the webhook is activated the Config Server will send a
|
|
<code class="literal">RefreshRemoteApplicationEvent</code> targeted at the applications it thinks
|
|
might have changed. The change detection can be strategized, but by
|
|
default it just looks for changes in files that match the application
|
|
name (e.g. "foo.properties" is targeted at the "foo" application, and
|
|
"application.properties" is targeted at all applications). The strategy
|
|
if you want to override the behaviour is <code class="literal">PropertyPathNotificationExtractor</code>
|
|
which accepts the request headers and body as parameters and returns a list
|
|
of file paths that changed.</p><p>The default configuration works out of the box with Github, Gitlab or
|
|
Bitbucket. In addition to the JSON notifications from Github, Gitlab
|
|
or Bitbucket you can trigger a change notification by POSTing to
|
|
"/monitor" with a form-encoded body parameters <code class="literal">path={name}</code>. This will
|
|
broadcast to applications matching the "{name}" pattern (can contain
|
|
wildcards).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the <code class="literal">RefreshRemoteApplicationEvent</code> will only be transmitted if
|
|
the <code class="literal">spring-cloud-bus</code> is activated in the Config Server and in the
|
|
client application.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the default configuration also detects filesystem changes in
|
|
local git repositories (the webhook is not used in that case but as
|
|
soon as you edit a config file a refresh will be broadcast).</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_config_client" href="#_spring_cloud_config_client"></a>10. Spring Cloud Config Client</h2></div></div></div><p>A Spring Boot application can take immediate advantage of the Spring
|
|
Config Server (or other external property sources provided by the
|
|
application developer), and it will also pick up some additional
|
|
useful features related to <code class="literal">Environment</code> change events.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="config-first-bootstrap" href="#config-first-bootstrap"></a>10.1 Config First Bootstrap</h2></div></div></div><p>This is the default behaviour for any application which has the Spring
|
|
Cloud Config Client on the classpath. When a config client starts up
|
|
it binds to the Config Server (via the bootstrap configuration
|
|
property <code class="literal">spring.cloud.config.uri</code>) and initializes Spring
|
|
<code class="literal">Environment</code> with remote property sources.</p><p>The net result of this is that all client apps that want to consume
|
|
the Config Server need a <code class="literal">bootstrap.yml</code> (or an environment variable)
|
|
with the server address in <code class="literal">spring.cloud.config.uri</code> (defaults to
|
|
"http://localhost:8888").</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="discovery-first-bootstrap" href="#discovery-first-bootstrap"></a>10.2 Discovery First Bootstrap</h2></div></div></div><p>If you are using a `DiscoveryClient implementation, such as Spring Cloud Netflix
|
|
and Eureka Service Discovery or Spring Cloud Consul (Spring Cloud Zookeeper does
|
|
not support this yet), then you can have the Config Server register with the
|
|
Discovery Service if you want to, but in the default "Config First" mode,
|
|
clients won’t be able to take advantage of the registration.</p><p>If you prefer to use <code class="literal">DiscoveryClient</code> to locate the Config Server, you can do
|
|
that by setting <code class="literal">spring.cloud.config.discovery.enabled=true</code> (default
|
|
"false"). The net result of that is that client apps all need a
|
|
<code class="literal">bootstrap.yml</code> (or an environment variable) with the appropriate discovery
|
|
configuration. For example, with Spring Cloud Netflix, you need to define the
|
|
Eureka server address, e.g. in <code class="literal">eureka.client.serviceUrl.defaultZone</code>. The
|
|
price for using this option is an extra network round trip on start up to
|
|
locate the service registration. The benefit is that the Config Server
|
|
can change its co-ordinates, as long as the Discovery Service is a fixed point. The
|
|
default service id is "configserver" but you can change that on the
|
|
client with <code class="literal">spring.cloud.config.discovery.serviceId</code> (and on the server
|
|
in the usual way for a service, e.g. by setting <code class="literal">spring.application.name</code>).</p><p>The discovery client implementations all support some kind of metadata
|
|
map (e.g. for Eureka we have <code class="literal">eureka.instance.metadataMap</code>). Some
|
|
additional properties of the Config Server may need to be configured
|
|
in its service registration metadata so that clients can connect
|
|
correctly. If the Config Server is secured with HTTP Basic you can
|
|
configure the credentials as "username" and "password". And if the
|
|
Config Server has a context path you can set "configPath". Example,
|
|
for a Config Server that is a Eureka client:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">eureka</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> instance</span>:
|
|
...
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> metadataMap</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> user</span>: osufhalskjrtl
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: lviuhlszvaorhvlo5847
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> configPath</span>: /config</pre><p>
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="config-client-fail-fast" href="#config-client-fail-fast"></a>10.3 Config Client Fail Fast</h2></div></div></div><p>In some cases, it may be desirable to fail startup of a service if
|
|
it cannot connect to the Config Server. If this is the desired
|
|
behavior, set the bootstrap configuration property
|
|
<code class="literal">spring.cloud.config.failFast=true</code> and the client will halt with
|
|
an Exception.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="config-client-retry" href="#config-client-retry"></a>10.4 Config Client Retry</h2></div></div></div><p>If you expect that the config server may occasionally be unavailable when
|
|
your app starts, you can ask it to keep trying after a failure. First you need
|
|
to set <code class="literal">spring.cloud.config.failFast=true</code>, and then you need to add
|
|
<code class="literal">spring-retry</code> and <code class="literal">spring-boot-starter-aop</code> to your classpath. The default
|
|
behaviour is to retry 6 times with an initial backoff interval of 1000ms and an
|
|
exponential multiplier of 1.1 for subsequent backoffs. You can configure these
|
|
properties (and others) using <code class="literal">spring.cloud.config.retry.*</code> configuration properties.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>To take full control of the retry add a <code class="literal">@Bean</code> of type
|
|
<code class="literal">RetryOperationsInterceptor</code> with id "configServerRetryInterceptor". Spring
|
|
Retry has a <code class="literal">RetryInterceptorBuilder</code> that makes it easy to create one.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_locating_remote_configuration_resources" href="#_locating_remote_configuration_resources"></a>10.5 Locating Remote Configuration Resources</h2></div></div></div><p>The Config Service serves property sources from <code class="literal">/{name}/{profile}/{label}</code>, where the default bindings in the client app are</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">"name" = <code class="literal">${spring.application.name}</code></li><li class="listitem">"profile" = <code class="literal">${spring.profiles.active}</code> (actually <code class="literal">Environment.getActiveProfiles()</code>)</li><li class="listitem">"label" = "master"</li></ul></div><p>All of them can be overridden by setting <code class="literal">spring.cloud.config.*</code>
|
|
(where <code class="literal">*</code> is "name", "profile" or "label"). The "label" is useful for
|
|
rolling back to previous versions of configuration; with the default
|
|
Config Server implementation it can be a git label, branch name or
|
|
commit id. Label can also be provided as a comma-separated list, in
|
|
which case the items in the list are tried on-by-one until one succeeds.
|
|
This can be useful when working on a feature branch, for instance,
|
|
when you might want to align the config label with your branch, but
|
|
make it optional (e.g. <code class="literal">spring.cloud.config.label=myfeature,develop</code>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_security_2" href="#_security_2"></a>10.6 Security</h2></div></div></div><p>If you use HTTP Basic security on the server then clients just need to
|
|
know the password (and username if it isn’t the default). You can do
|
|
that via the config server URI, or via separate username and password
|
|
properties, e.g.</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://user:secret@myconfig.mycompany.com</pre><p>
|
|
</p><p>or</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: https://myconfig.mycompany.com
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username</span>: user
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: secret</pre><p>
|
|
</p><p>The <code class="literal">spring.cloud.config.password</code> and <code class="literal">spring.cloud.config.username</code>
|
|
values override anything that is provided in the URI.</p><p>If you deploy your apps on Cloud Foundry then the best way to provide
|
|
the password is through service credentials, e.g. in the URI, since
|
|
then it doesn’t even need to be in a config file. An example which
|
|
works locally and for a user-provided service on Cloud Foundry named
|
|
"configserver":</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: ${vcap.services.configserver.credentials.uri:http://user:password@localhost:<span class="hl-number">8888</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
|
|
</p><p>If you use another form of security you might need to <a class="link" href="#custom-rest-template" title="10.6.2 Providing A Custom RestTemplate">provide a
|
|
<code class="literal">RestTemplate</code></a> to the <code class="literal">ConfigServicePropertySourceLocator</code> (e.g. by
|
|
grabbing it in the bootstrap context and injecting one).</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_health_indicator_2" href="#_health_indicator_2"></a>10.6.1 Health Indicator</h3></div></div></div><p>The Config Client supplies a Spring Boot Health Indicator that attempts to load configuration from Config Server. The health indicator can be disabled by setting <code class="literal">health.config.enabled=false</code>. The response is also cached for performance reasons. The default cache time to live is 5 minutes. To change that value set the <code class="literal">health.config.time-to-live</code> property (in milliseconds).</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="custom-rest-template" href="#custom-rest-template"></a>10.6.2 Providing A Custom RestTemplate</h3></div></div></div><p>In some cases you might need to customize the requests made to the config server from
|
|
the client. Typically this involves passing special <code class="literal">Authorization</code> headers to
|
|
authenticate requests to the server. To provide a custom <code class="literal">RestTemplate</code> follow the
|
|
steps below.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Create a new configuration bean with an implementation of <code class="literal">PropertySourceLocator</code>.</li></ol></div><p><b>CustomConfigServiceBootstrapConfiguration.java. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomConfigServiceBootstrapConfiguration {
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ConfigServicePropertySourceLocator configServicePropertySourceLocator() {
|
|
ConfigClientProperties clientProperties = configClientProperties();
|
|
ConfigServicePropertySourceLocator configServicePropertySourceLocator = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ConfigServicePropertySourceLocator(clientProperties);
|
|
configServicePropertySourceLocator.setRestTemplate(customRestTemplate(clientProperties));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> configServicePropertySourceLocator;
|
|
}
|
|
}</pre><p>
|
|
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">In <code class="literal">resources/META-INF</code> create a file called
|
|
<code class="literal">spring.factories</code> and specify your custom configuration.</li></ol></div><p><b>spring.factories. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">org.springframework.cloud.bootstrap.BootstrapConfiguration </span>= com.my.config.client.CustomConfigServiceBootstrapConfiguration</pre><p>
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_vault" href="#_vault"></a>10.6.3 Vault</h3></div></div></div><p>When using Vault as a backend to your config server the client will need to
|
|
supply a token for the server to retrieve values from Vault. This token
|
|
can be provided within the client by setting <code class="literal">spring.cloud.config.token</code>
|
|
in <code class="literal">bootstrap.yml</code>.</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> token</span>: YourVaultToken</pre><p>
|
|
</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_vault_2" href="#_vault_2"></a>10.7 Vault</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_nested_keys_in_vault" href="#_nested_keys_in_vault"></a>10.7.1 Nested Keys In Vault</h3></div></div></div><p>Vault supports the ability to nest keys in a value stored in Vault. For example</p><p><code class="literal">echo -n '{"appA": {"secret": "appAsecret"}, "bar": "baz"}' | vault write secret/myapp -</code></p><p>This command will write a JSON object to your Vault. To access these values in Spring
|
|
you would use the traditional dot(.) annotation. For example</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Value("${appA.secret}")</span></em>
|
|
String name = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"World"</span>;</pre><p>The above code would set the <code class="literal">name</code> variable to <code class="literal">appAsecret</code>.</p></div></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_netflix" href="#_spring_cloud_netflix"></a>Part III. Spring Cloud Netflix</h1></div></div></div><div class="partintro"><div></div><p><span class="strong"><strong>Dalston.SR4</strong></span></p><p>This project provides Netflix OSS integrations for Spring Boot apps through autoconfiguration
|
|
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
|
simple annotations you can quickly enable and configure the common patterns inside your
|
|
application and build large distributed systems with battle-tested Netflix components. The
|
|
patterns provided include Service Discovery (Eureka), Circuit Breaker (Hystrix),
|
|
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon).</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_service_discovery_eureka_clients" href="#_service_discovery_eureka_clients"></a>11. Service Discovery: Eureka Clients</h2></div></div></div><p>Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. Eureka is the Netflix Service Discovery Server and Client. The server can be configured and deployed to be highly available, with each server replicating state about the registered services to the others.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-eureka-client-starter" href="#netflix-eureka-client-starter"></a>11.1 How to Include Eureka Client</h2></div></div></div><p>To include Eureka Client in your project use the starter with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-starter-eureka</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
|
|
for details on setting up your build system with the current Spring Cloud Release Train.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_with_eureka" href="#_registering_with_eureka"></a>11.2 Registering with Eureka</h2></div></div></div><p>When a client registers with Eureka, it provides meta-data about itself
|
|
such as host and port, health indicator URL, home page etc. Eureka
|
|
receives heartbeat messages from each instance belonging to a service.
|
|
If the heartbeat fails over a configurable timetable, the instance is
|
|
normally removed from the registry.</p><p>Example eureka client:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ComponentScan</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableEurekaClient</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping("/")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String home() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello world"</span>;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SpringApplicationBuilder(Application.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).web(true).run(args);
|
|
}
|
|
|
|
}</pre><p>(i.e. utterly normal Spring Boot app). In this example we use
|
|
<code class="literal">@EnableEurekaClient</code> explicitly, but with only Eureka available you
|
|
could also use <code class="literal">@EnableDiscoveryClient</code>. Configuration is required to
|
|
locate the Eureka server. Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">eureka:
|
|
client:
|
|
serviceUrl:
|
|
defaultZone: http://localhost:8761/eureka/</pre><p>
|
|
</p><p>where "defaultZone" is a magic string fallback value that provides the
|
|
service URL for any client that doesn’t express a preference
|
|
(i.e. it’s a useful default).</p><p>The default application name (service ID), virtual host and non-secure
|
|
port, taken from the <code class="literal">Environment</code>, are <code class="literal">${spring.application.name}</code>,
|
|
<code class="literal">${spring.application.name}</code> and <code class="literal">${server.port}</code> respectively.</p><p><code class="literal">@EnableEurekaClient</code> makes the app into both a Eureka "instance"
|
|
(i.e. it registers itself) and a "client" (i.e. it can query the
|
|
registry to locate other services). The instance behaviour is driven
|
|
by <code class="literal">eureka.instance.*</code> configuration keys, but the defaults will be
|
|
fine if you ensure that your application has a
|
|
<code class="literal">spring.application.name</code> (this is the default for the Eureka service
|
|
ID, or VIP).</p><p>See <a class="link" href="http://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaInstanceConfigBean.java" target="_top">EurekaInstanceConfigBean</a> and <a class="link" href="http://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaClientConfigBean.java" target="_top">EurekaClientConfigBean</a> for more details of the configurable options.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_authenticating_with_the_eureka_server" href="#_authenticating_with_the_eureka_server"></a>11.3 Authenticating with the Eureka Server</h2></div></div></div><p>HTTP basic authentication will be automatically added to your eureka
|
|
client if one of the <code class="literal">eureka.client.serviceUrl.defaultZone</code> URLs has
|
|
credentials embedded in it (curl style, like
|
|
<code class="literal"><a class="link" href="http://user:password@localhost:8761/eureka" target="_top">http://user:password@localhost:8761/eureka</a></code>). For more complex needs
|
|
you can create a <code class="literal">@Bean</code> of type <code class="literal">DiscoveryClientOptionalArgs</code> and
|
|
inject <code class="literal">ClientFilter</code> instances into it, all of which will be applied
|
|
to the calls from the client to the server.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Because of a limitation in Eureka it isn’t possible to support
|
|
per-server basic auth credentials, so only the first set that are
|
|
found will be used.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_status_page_and_health_indicator" href="#_status_page_and_health_indicator"></a>11.4 Status Page and Health Indicator</h2></div></div></div><p>The status page and health indicators for a Eureka instance default to
|
|
"/info" and "/health" respectively, which are the default locations of
|
|
useful endpoints in a Spring Boot Actuator application. You need to
|
|
change these, even for an Actuator application if you use a
|
|
non-default context path or servlet path
|
|
(e.g. <code class="literal">server.servletPath=/foo</code>) or management endpoint path
|
|
(e.g. <code class="literal">management.contextPath=/admin</code>). Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">eureka:
|
|
instance:
|
|
statusPageUrlPath: ${management.context-path}/info
|
|
healthCheckUrlPath: ${management.context-path}/health</pre><p>
|
|
</p><p>These links show up in the metadata that is consumed by clients, and
|
|
used in some scenarios to decide whether to send requests to your
|
|
application, so it’s helpful if they are accurate.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_a_secure_application" href="#_registering_a_secure_application"></a>11.5 Registering a Secure Application</h2></div></div></div><p>If your app wants to be contacted over HTTPS you can set two flags in
|
|
the <code class="literal">EurekaInstanceConfig</code>, <span class="emphasis"><em>viz</em></span>
|
|
<code class="literal">eureka.instance.[nonSecurePortEnabled,securePortEnabled]=[false,true]</code>
|
|
respectively. This will make Eureka publish instance information
|
|
showing an explicit preference for secure communication. The Spring
|
|
Cloud <code class="literal">DiscoveryClient</code> will always return a URI starting with <code class="literal">https</code> for a
|
|
service configured this way, and the Eureka (native) instance
|
|
information will have a secure health check URL.</p><p>Because of the way
|
|
Eureka works internally, it will still publish a non-secure URL for
|
|
status and home page unless you also override those explicitly.
|
|
You can use placeholders to configure the eureka instance urls,
|
|
e.g.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">eureka:
|
|
instance:
|
|
statusPageUrl: https://${eureka.hostname}/info
|
|
healthCheckUrl: https://${eureka.hostname}/health
|
|
homePageUrl: https://${eureka.hostname}/</pre><p>
|
|
</p><p>(Note that <code class="literal">${eureka.hostname}</code> is a native placeholder only available
|
|
in later versions of Eureka. You could achieve the same thing with
|
|
Spring placeholders as well, e.g. using <code class="literal">${eureka.instance.hostName}</code>.)</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If your app is running behind a proxy, and the SSL termination
|
|
is in the proxy (e.g. if you run in Cloud Foundry or other platforms
|
|
as a service) then you will need to ensure that the proxy "forwarded"
|
|
headers are intercepted and handled by the application. An embedded
|
|
Tomcat container in a Spring Boot app does this automatically if it
|
|
has explicit configuration for the 'X-Forwarded-\*` headers. A sign
|
|
that you got this wrong will be that the links rendered by your app to
|
|
itself will be wrong (the wrong host, port or protocol).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_eureka_s_health_checks" href="#_eureka_s_health_checks"></a>11.6 Eureka’s Health Checks</h2></div></div></div><p>By default, Eureka uses the client heartbeat to determine if a client is up.
|
|
Unless specified otherwise the Discovery Client will not propagate the
|
|
current health check status of the application per the Spring Boot Actuator. Which means
|
|
that after successful registration Eureka will always announce that the
|
|
application is in 'UP' state. This behaviour can be altered by enabling
|
|
Eureka health checks, which results in propagating application status
|
|
to Eureka. As a consequence every other application won’t be sending
|
|
traffic to application in state other then 'UP'.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">eureka:
|
|
client:
|
|
healthcheck:
|
|
enabled: true</pre><p>
|
|
</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p><code class="literal">eureka.client.healthcheck.enabled=true</code> should only be set in <code class="literal">application.yml</code>. Setting the value in <code class="literal">bootstrap.yml</code> will cause undesirable side effects like registering in eureka with an <code class="literal">UNKNOWN</code> status.</p></td></tr></table></div><p>If you require more control over the health checks, you may consider
|
|
implementing your own <code class="literal">com.netflix.appinfo.HealthCheckHandler</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_eureka_metadata_for_instances_and_clients" href="#_eureka_metadata_for_instances_and_clients"></a>11.7 Eureka Metadata for Instances and Clients</h2></div></div></div><p>It’s worth spending a bit of time understanding how the Eureka metadata works, so you can use it in a way that makes sense in your platform. There is standard metadata for things like hostname, IP address, port numbers, status page and health check. These are published in the service registry and used by clients to contact the services in a straightforward way. Additional metadata can be added to the instance registration in the <code class="literal">eureka.instance.metadataMap</code>, and this will be accessible in the remote clients, but in general will not change the behaviour of the client, unless it is made aware of the meaning of the metadata. There are a couple of special cases described below where Spring Cloud already assigns meaning to the metadata map.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_using_eureka_on_cloudfoundry" href="#_using_eureka_on_cloudfoundry"></a>11.7.1 Using Eureka on Cloudfoundry</h3></div></div></div><p>Cloudfoundry has a global router so that all instances of the same app have the same hostname (it’s the same in other PaaS solutions with a similar architecture). This isn’t necessarily a barrier to using Eureka, but if you use the router (recommended, or even mandatory depending on the way your platform was set up), you need to explicitly set the hostname and port numbers (secure or non-secure) so that they use the router. You might also want to use instance metadata so you can distinguish between the instances on the client (e.g. in a custom load balancer). By default, the <code class="literal">eureka.instance.instanceId</code> is <code class="literal">vcap.application.instance_id</code>. For example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">eureka:
|
|
instance:
|
|
hostname: ${vcap.application.uris[0]}
|
|
nonSecurePort: 80</pre><p>
|
|
</p><p>Depending on the way the security rules are set up in your Cloudfoundry instance, you might be able to register and use the IP address of the host VM for direct service-to-service calls. This feature is not (yet) available on Pivotal Web Services (<a class="link" href="https://run.pivotal.io" target="_top">PWS</a>).</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_using_eureka_on_aws" href="#_using_eureka_on_aws"></a>11.7.2 Using Eureka on AWS</h3></div></div></div><p>If the application is planned to be deployed to an AWS cloud, then the Eureka instance will have to be configured to be AWS aware and this can be done by customizing the <a class="link" href="http://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-eureka-client/src/main/java/org/springframework/cloud/netflix/eureka/EurekaInstanceConfigBean.java" target="_top">EurekaInstanceConfigBean</a> the following way:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Profile("!default")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> EurekaInstanceConfigBean eurekaInstanceConfig(InetUtils inetUtils) {
|
|
EurekaInstanceConfigBean b = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> EurekaInstanceConfigBean(inetUtils);
|
|
AmazonInfo info = AmazonInfo.Builder.newBuilder().autoBuild(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"eureka"</span>);
|
|
b.setDataCenterInfo(info);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> b;
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_changing_the_eureka_instance_id" href="#_changing_the_eureka_instance_id"></a>11.7.3 Changing the Eureka Instance ID</h3></div></div></div><p>A vanilla Netflix Eureka instance is registered with an ID that is equal to its host name (i.e. only one service per host). Spring Cloud Eureka provides a sensible default that looks like this: <code class="literal">${spring.cloud.client.hostname}:${spring.application.name}:${spring.application.instance_id:${server.port}}}</code>. For example <code class="literal">myhost:myappname:8080</code>.</p><p>Using Spring Cloud you can override this by providing a unique identifier in <code class="literal">eureka.instance.instanceId</code>. For example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">eureka:
|
|
instance:
|
|
instanceId: ${spring.application.name}:${vcap.application.instance_id:${spring.application.instance_id:${random.value}}}</pre><p>
|
|
</p><p>With this metadata, and multiple service instances deployed on
|
|
localhost, the random value will kick in there to make the instance
|
|
unique. In Cloudfoundry the <code class="literal">vcap.application.instance_id</code> will be
|
|
populated automatically in a Spring Boot application, so the
|
|
random value will not be needed.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_the_eurekaclient" href="#_using_the_eurekaclient"></a>11.8 Using the EurekaClient</h2></div></div></div><p>Once you have an app that is <code class="literal">@EnableDiscoveryClient</code> (or <code class="literal">@EnableEurekaClient</code>) you can use it to
|
|
discover service instances from the <a class="link" href="#spring-cloud-eureka-server" title="12. Service Discovery: Eureka Server">Eureka Server</a>. One way to do that is to use the native
|
|
<code class="literal">com.netflix.discovery.EurekaClient</code> (as opposed to the Spring
|
|
Cloud <code class="literal">DiscoveryClient</code>), e.g.</p><pre class="screen">@Autowired
|
|
private EurekaClient discoveryClient;
|
|
|
|
public String serviceUrl() {
|
|
InstanceInfo instance = discoveryClient.getNextServerFromEureka("STORES", false);
|
|
return instance.getHomePageUrl();
|
|
}</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Don’t use the <code class="literal">EurekaClient</code> in <code class="literal">@PostConstruct</code> method or in a
|
|
<code class="literal">@Scheduled</code> method (or anywhere where the <code class="literal">ApplicationContext</code> might
|
|
not be started yet). It is initialized in a <code class="literal">SmartLifecycle</code> (with
|
|
<code class="literal">phase=0</code>) so the earliest you can rely on it being available is in
|
|
another <code class="literal">SmartLifecycle</code> with higher phase.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_alternatives_to_the_native_netflix_eurekaclient" href="#_alternatives_to_the_native_netflix_eurekaclient"></a>11.9 Alternatives to the native Netflix EurekaClient</h2></div></div></div><p>You don’t have to use the raw Netflix <code class="literal">EurekaClient</code> and usually it
|
|
is more convenient to use it behind a wrapper of some sort. Spring
|
|
Cloud has support for <a class="link" href="#spring-cloud-feign" title="17. Declarative REST Client: Feign">Feign</a> (a REST client
|
|
builder) and also <a class="link" href="#spring-cloud-ribbon" title="16. Client Side Load Balancer: Ribbon">Spring <code class="literal">RestTemplate</code></a> using
|
|
the logical Eureka service identifiers (VIPs) instead of physical
|
|
URLs. To configure Ribbon with a fixed list of physical servers you
|
|
can simply set <code class="literal"><client>.ribbon.listOfServers</code> to a comma-separated
|
|
list of physical addresses (or hostnames), where <code class="literal"><client></code> is the ID
|
|
of the client.</p><p>You can also use the <code class="literal">org.springframework.cloud.client.discovery.DiscoveryClient</code>
|
|
which provides a simple API for discovery clients that is not specific
|
|
to Netflix, e.g.</p><pre class="screen">@Autowired
|
|
private DiscoveryClient discoveryClient;
|
|
|
|
public String serviceUrl() {
|
|
List<ServiceInstance> list = discoveryClient.getInstances("STORES");
|
|
if (list != null && list.size() > 0 ) {
|
|
return list.get(0).getUri();
|
|
}
|
|
return null;
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_why_is_it_so_slow_to_register_a_service" href="#_why_is_it_so_slow_to_register_a_service"></a>11.10 Why is it so Slow to Register a Service?</h2></div></div></div><p>Being an instance also involves a periodic heartbeat to the registry
|
|
(via the client’s <code class="literal">serviceUrl</code>) with default duration 30 seconds. A
|
|
service is not available for discovery by clients until the instance,
|
|
the server and the client all have the same metadata in their local
|
|
cache (so it could take 3 heartbeats). You can change the period using
|
|
<code class="literal">eureka.instance.leaseRenewalIntervalInSeconds</code> and this will speed up
|
|
the process of getting clients connected to other services. In
|
|
production it’s probably better to stick with the default because
|
|
there are some computations internally in the server that make
|
|
assumptions about the lease renewal period.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_zones" href="#_zones"></a>11.11 Zones</h2></div></div></div><p>If you have deployed Eureka clients to multiple zones than you may prefer that
|
|
those clients leverage services within the same zone before trying services
|
|
in another zone. To do this you need to configure your Eureka clients correctly.</p><p>First, you need to make sure you have Eureka servers deployed to each zone and that
|
|
they are peers of each other. See the section on <a class="link" href="#spring-cloud-eureka-server-zones-and-regions" title="12.3 High Availability, Zones and Regions">zones and regions</a>
|
|
for more information.</p><p>Next you need to tell Eureka which zone your service is in. You can do this using
|
|
the <code class="literal">metadataMap</code> property. For example if <code class="literal">service 1</code> is deployed to both <code class="literal">zone 1</code>
|
|
and <code class="literal">zone 2</code> you would need to set the following Eureka properties in <code class="literal">service 1</code></p><p><span class="strong"><strong>Service 1 in Zone 1</strong></span></p><pre class="screen">eureka.instance.metadataMap.zone = zone1
|
|
eureka.client.preferSameZoneEureka = true</pre><p><span class="strong"><strong>Service 1 in Zone 2</strong></span></p><pre class="screen">eureka.instance.metadataMap.zone = zone2
|
|
eureka.client.preferSameZoneEureka = true</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-eureka-server" href="#spring-cloud-eureka-server"></a>12. Service Discovery: Eureka Server</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-eureka-server-starter" href="#netflix-eureka-server-starter"></a>12.1 How to Include Eureka Server</h2></div></div></div><p>To include Eureka Server in your project use the starter with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-starter-eureka-server</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
|
|
for details on setting up your build system with the current Spring Cloud Release Train.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-running-eureka-server" href="#spring-cloud-running-eureka-server"></a>12.2 How to Run a Eureka Server</h2></div></div></div><p>Example eureka server;</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableEurekaServer</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SpringApplicationBuilder(Application.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).web(true).run(args);
|
|
}
|
|
|
|
}</pre><p>The server has a home page with a UI, and HTTP API endpoints per the
|
|
normal Eureka functionality under <code class="literal">/eureka/*</code>.</p><p>Eureka background reading: see <a class="link" href="https://github.com/cfregly/fluxcapacitor/wiki/NetflixOSS-FAQ#eureka-service-discovery-load-balancer" target="_top">flux capacitor</a> and <a class="link" href="https://groups.google.com/forum/?fromgroups#!topic/eureka_netflix/g3p2r7gHnN0" target="_top">google group discussion</a>.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Due to Gradle’s dependency resolution rules and the lack of a parent bom feature, simply depending on spring-cloud-starter-eureka-server can cause failures on application startup. To remedy this the Spring Boot Gradle plugin must be added and the Spring cloud starter parent bom must be imported like so:</p><p><b>build.gradle. </b>
|
|
</p><pre class="programlisting">buildscript {
|
|
dependencies {
|
|
classpath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.boot:spring-boot-gradle-plugin:1.3.5.RELEASE"</span>)
|
|
}
|
|
}
|
|
|
|
apply plugin: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spring-boot"</span>
|
|
|
|
dependencyManagement {
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"</span>
|
|
}
|
|
}</pre><p>
|
|
</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-eureka-server-zones-and-regions" href="#spring-cloud-eureka-server-zones-and-regions"></a>12.3 High Availability, Zones and Regions</h2></div></div></div><p>The Eureka server does not have a backend store, but the service
|
|
instances in the registry all have to send heartbeats to keep their
|
|
registrations up to date (so this can be done in memory). Clients also
|
|
have an in-memory cache of eureka registrations (so they don’t have to
|
|
go to the registry for every single request to a service).</p><p>By default every Eureka server is also a Eureka client and requires
|
|
(at least one) service URL to locate a peer. If you don’t provide it
|
|
the service will run and work, but it will shower your logs with a lot
|
|
of noise about not being able to register with the peer.</p><p>See also <a class="link" href="#spring-cloud-ribbon" title="16. Client Side Load Balancer: Ribbon">below for details of Ribbon
|
|
support</a> on the client side for Zones and Regions.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_standalone_mode" href="#_standalone_mode"></a>12.4 Standalone Mode</h2></div></div></div><p>The combination of the two caches (client and server) and the
|
|
heartbeats make a standalone Eureka server fairly resilient to
|
|
failure, as long as there is some sort of monitor or elastic runtime
|
|
keeping it alive (e.g. Cloud Foundry). In standalone mode, you might
|
|
prefer to switch off the client side behaviour, so it doesn’t keep
|
|
trying and failing to reach its peers. Example:</p><p><b>application.yml (Standalone Eureka Server). </b>
|
|
</p><pre class="screen">server:
|
|
port: 8761
|
|
|
|
eureka:
|
|
instance:
|
|
hostname: localhost
|
|
client:
|
|
registerWithEureka: false
|
|
fetchRegistry: false
|
|
serviceUrl:
|
|
defaultZone: http://${eureka.instance.hostname}:${server.port}/eureka/</pre><p>
|
|
</p><p>Notice that the <code class="literal">serviceUrl</code> is pointing to the same host as the local
|
|
instance.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_peer_awareness" href="#_peer_awareness"></a>12.5 Peer Awareness</h2></div></div></div><p>Eureka can be made even more resilient and available by running
|
|
multiple instances and asking them to register with each other. In
|
|
fact, this is the default behaviour, so all you need to do to make it
|
|
work is add a valid <code class="literal">serviceUrl</code> to a peer, e.g.</p><p><b>application.yml (Two Peer Aware Eureka Servers). </b>
|
|
</p><pre class="screen">---
|
|
spring:
|
|
profiles: peer1
|
|
eureka:
|
|
instance:
|
|
hostname: peer1
|
|
client:
|
|
serviceUrl:
|
|
defaultZone: http://peer2/eureka/
|
|
|
|
---
|
|
spring:
|
|
profiles: peer2
|
|
eureka:
|
|
instance:
|
|
hostname: peer2
|
|
client:
|
|
serviceUrl:
|
|
defaultZone: http://peer1/eureka/</pre><p>
|
|
</p><p>In this example we have a YAML file that can be used to run the same
|
|
server on 2 hosts (peer1 and peer2), by running it in different
|
|
Spring profiles. You could use this configuration to test the peer
|
|
awareness on a single host (there’s not much value in doing that in
|
|
production) by manipulating <code class="literal">/etc/hosts</code> to resolve the host names. In
|
|
fact, the <code class="literal">eureka.instance.hostname</code> is not needed if you are running
|
|
on a machine that knows its own hostname (it is looked up using
|
|
<code class="literal">java.net.InetAddress</code> by default).</p><p>You can add multiple peers to a system, and as long as they are all
|
|
connected to each other by at least one edge, they will synchronize
|
|
the registrations amongst themselves. If the peers are physically
|
|
separated (inside a data centre or between multiple data centres) then
|
|
the system can in principle survive split-brain type failures.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_prefer_ip_address" href="#_prefer_ip_address"></a>12.6 Prefer IP Address</h2></div></div></div><p>In some cases, it is preferable for Eureka to advertise the IP Adresses
|
|
of services rather than the hostname. Set <code class="literal">eureka.instance.preferIpAddress</code>
|
|
to <code class="literal">true</code> and when the application registers with eureka, it will use its
|
|
IP Address rather than its hostname.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_circuit_breaker_hystrix_clients" href="#_circuit_breaker_hystrix_clients"></a>13. Circuit Breaker: Hystrix Clients</h2></div></div></div><p>Netflix has created a library called <a class="link" href="https://github.com/Netflix/Hystrix" target="_top">Hystrix</a> that implements the <a class="link" href="http://martinfowler.com/bliki/CircuitBreaker.html" target="_top">circuit breaker pattern</a>. In a microservice architecture it is common to have multiple layers of service calls.</p><div class="figure"><a name="d0e3031" href="#d0e3031"></a><p class="title"><b>Figure 13.1. Microservice Graph</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/HystrixGraph.png" alt="HystrixGraph"></div></div></div><br class="figure-break"><p>A service failure in the lower level of services can cause cascading failure all the way up to the user. When calls to a particular service is greater than <code class="literal">circuitBreaker.requestVolumeThreshold</code> (default: 20 requests) and failue percentage is greater than <code class="literal">circuitBreaker.errorThresholdPercentage</code> (default: >50%) in a rolling window defined by <code class="literal">metrics.rollingStats.timeInMilliseconds</code> (default: 10 seconds), the circuit opens and the call is not made. In cases of error and an open circuit a fallback can be provided by the developer.</p><div class="figure"><a name="d0e3051" href="#d0e3051"></a><p class="title"><b>Figure 13.2. Hystrix fallback prevents cascading failures</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/HystrixFallback.png" alt="HystrixFallback"></div></div></div><br class="figure-break"><p>Having an open circuit stops cascading failures and allows overwhelmed or failing services time to heal. The fallback can be another Hystrix protected call, static data or a sane empty value. Fallbacks may be chained so the first fallback makes some other business call which in turn falls back to static data.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-hystrix-starter" href="#netflix-hystrix-starter"></a>13.1 How to Include Hystrix</h2></div></div></div><p>To include Hystrix in your project use the starter with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-starter-hystrix</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
|
|
for details on setting up your build system with the current Spring Cloud Release Train.</p><p>Example boot app:</p><pre class="screen">@SpringBootApplication
|
|
@EnableCircuitBreaker
|
|
public class Application {
|
|
|
|
public static void main(String[] args) {
|
|
new SpringApplicationBuilder(Application.class).web(true).run(args);
|
|
}
|
|
|
|
}
|
|
|
|
@Component
|
|
public class StoreIntegration {
|
|
|
|
@HystrixCommand(fallbackMethod = "defaultStores")
|
|
public Object getStores(Map<String, Object> parameters) {
|
|
//do stuff that might fail
|
|
}
|
|
|
|
public Object defaultStores(Map<String, Object> parameters) {
|
|
return /* something useful */;
|
|
}
|
|
}</pre><p>The <code class="literal">@HystrixCommand</code> is provided by a Netflix contrib library called
|
|
<a class="link" href="https://github.com/Netflix/Hystrix/tree/master/hystrix-contrib/hystrix-javanica" target="_top">"javanica"</a>.
|
|
Spring Cloud automatically wraps Spring beans with that
|
|
annotation in a proxy that is connected to the Hystrix circuit
|
|
breaker. The circuit breaker calculates when to open and close the
|
|
circuit, and what to do in case of a failure.</p><p>To configure the <code class="literal">@HystrixCommand</code> you can use the <code class="literal">commandProperties</code>
|
|
attribute with a list of <code class="literal">@HystrixProperty</code> annotations. See
|
|
<a class="link" href="https://github.com/Netflix/Hystrix/tree/master/hystrix-contrib/hystrix-javanica#configuration" target="_top">here</a>
|
|
for more details. See the <a class="link" href="https://github.com/Netflix/Hystrix/wiki/Configuration" target="_top">Hystrix wiki</a>
|
|
for details on the properties available.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_propagating_the_security_context_or_using_spring_scopes" href="#_propagating_the_security_context_or_using_spring_scopes"></a>13.2 Propagating the Security Context or using Spring Scopes</h2></div></div></div><p>If you want some thread local context to propagate into a <code class="literal">@HystrixCommand</code> the default declaration will not work because it executes the command in a thread pool (in case of timeouts). You can switch Hystrix to use the same thread as the caller using some configuration, or directly in the annotation, by asking it to use a different "Isolation Strategy". For example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@HystrixCommand(fallbackMethod = "stubMyService",
|
|
commandProperties = {
|
|
@HystrixProperty(name="execution.isolation.strategy", value="SEMAPHORE")
|
|
}
|
|
)</span></em>
|
|
...</pre><p>The same thing applies if you are using <code class="literal">@SessionScope</code> or <code class="literal">@RequestScope</code>. You will know when you need to do this because of a runtime exception that says it can’t find the scoped context.</p><p>You also have the option to set the <code class="literal">hystrix.shareSecurityContext</code> property to <code class="literal">true</code>. Doing so will auto configure an Hystrix concurrency strategy plugin hook who will transfer the <code class="literal">SecurityContext</code> from your main thread to the one used by the Hystrix command. Hystrix does not allow multiple hystrix concurrency strategy to be registered so an extension mechanism is available by declaring your own <code class="literal">HystrixConcurrencyStrategy</code> as a Spring bean. Spring Cloud will lookup for your implementation within the Spring context and wrap it inside its own plugin.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_health_indicator_3" href="#_health_indicator_3"></a>13.3 Health Indicator</h2></div></div></div><p>The state of the connected circuit breakers are also exposed in the
|
|
<code class="literal">/health</code> endpoint of the calling application.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"hystrix"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"openCircuitBreakers"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"StoreIntegration::getStoresByLocationLink"</span>
|
|
]<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"CIRCUIT_OPEN"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"UP"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_hystrix_metrics_stream" href="#_hystrix_metrics_stream"></a>13.4 Hystrix Metrics Stream</h2></div></div></div><p>To enable the Hystrix metrics stream include a dependency on <code class="literal">spring-boot-starter-actuator</code>. This will expose the <code class="literal">/hystrix.stream</code> as a management endpoint.</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.boot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-boot-starter-actuator<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_circuit_breaker_hystrix_dashboard" href="#_circuit_breaker_hystrix_dashboard"></a>14. Circuit Breaker: Hystrix Dashboard</h2></div></div></div><p>One of the main benefits of Hystrix is the set of metrics it gathers about each HystrixCommand. The Hystrix Dashboard displays the health of each circuit breaker in an efficient manner.</p><div class="figure"><a name="d0e3165" href="#d0e3165"></a><p class="title"><b>Figure 14.1. Hystrix Dashboard</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/Hystrix.png" alt="Hystrix"></div></div></div><br class="figure-break"></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_hystrix_timeouts_and_ribbon_clients" href="#_hystrix_timeouts_and_ribbon_clients"></a>15. Hystrix Timeouts And Ribbon Clients</h2></div></div></div><p>When using Hystrix commands that wrap Ribbon clients you want to make sure your Hystrix timeout
|
|
is configured to be longer than the configured Ribbon timeout, including any potential
|
|
retries that might be made. For example, if your Ribbon connection timeout is one second and
|
|
the Ribbon client might retry the request three times, than your Hystrix timeout should
|
|
be slightly more than three seconds.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-hystrix-dashboard-starter" href="#netflix-hystrix-dashboard-starter"></a>15.1 How to Include Hystrix Dashboard</h2></div></div></div><p>To include the Hystrix Dashboard in your project use the starter with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-starter-hystrix-dashboard</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
|
|
for details on setting up your build system with the current Spring Cloud Release Train.</p><p>To run the Hystrix Dashboard annotate your Spring Boot main class with <code class="literal">@EnableHystrixDashboard</code>. You then visit <code class="literal">/hystrix</code> and point the dashboard to an individual instances <code class="literal">/hystrix.stream</code> endpoint in a Hystrix client application.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When connecting to a <code class="literal">/hystrix.stream</code> endpoint which uses HTTPS the certificate used by the server
|
|
must be trusted by the JVM. If the certificate is not trusted you must import the certificate into the JVM
|
|
in order for the Hystrix Dashboard to make a successful connection to the stream endpoint.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_turbine" href="#_turbine"></a>15.2 Turbine</h2></div></div></div><p>Looking at an individual instances Hystrix data is not very useful in terms of the overall health of the system. <a class="link" href="https://github.com/Netflix/Turbine" target="_top">Turbine</a> is an application that aggregates all of the relevant <code class="literal">/hystrix.stream</code> endpoints into a combined <code class="literal">/turbine.stream</code> for use in the Hystrix Dashboard. Individual instances are located via Eureka. Running Turbine is as simple as annotating your main class with the <code class="literal">@EnableTurbine</code> annotation (e.g. using spring-cloud-starter-turbine to set up the classpath). All of the documented configuration properties from <a class="link" href="https://github.com/Netflix/Turbine/wiki/Configuration-(1.x)" target="_top">the Turbine 1 wiki</a> apply. The only difference is that the <code class="literal">turbine.instanceUrlSuffix</code> does not need the port prepended as this is handled automatically unless <code class="literal">turbine.instanceInsertPort=false</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>By default, Turbine looks for the <code class="literal">/hystrix.stream</code> endpoint on a registered instance by looking up its <code class="literal">homePageUrl</code> entry in Eureka, then appending <code class="literal">/hystrix.stream</code> to it. This means that if <code class="literal">spring-boot-actuator</code> is running on its own port (which is the default), the call to <code class="literal">/hystrix.stream</code> will fail.
|
|
To make turbine find the Hystrix stream at the correct port, you need to add <code class="literal">management.port</code> to the instances' metadata:</p></td></tr></table></div><pre class="screen">eureka:
|
|
instance:
|
|
metadata-map:
|
|
management.port: ${management.port:8081}</pre><p>The configuration key <code class="literal">turbine.appConfig</code> is a list of eureka serviceIds that turbine will use to lookup instances. The turbine stream is then used in the Hystrix dashboard using a url that looks like: <code class="literal"><a class="link" href="http://my.turbine.sever:8080/turbine.stream?cluster=CLUSTERNAME" target="_top">http://my.turbine.sever:8080/turbine.stream?cluster=CLUSTERNAME</a></code> (the cluster parameter can be omitted if the name is "default"). The <code class="literal">cluster</code> parameter must match an entry in <code class="literal">turbine.aggregator.clusterConfig</code>. Values returned from eureka are uppercase, thus we expect this example to work if there is an app registered with Eureka called "customers":</p><pre class="screen">turbine:
|
|
aggregator:
|
|
clusterConfig: CUSTOMERS
|
|
appConfig: customers</pre><p>The <code class="literal">clusterName</code> can be customized by a SPEL expression in <code class="literal">turbine.clusterNameExpression</code> with root an instance of <code class="literal">InstanceInfo</code>. The default value is <code class="literal">appName</code>, which means that the Eureka serviceId ends up as the cluster key (i.e. the <code class="literal">InstanceInfo</code> for customers has an <code class="literal">appName</code> of "CUSTOMERS"). A different example would be <code class="literal">turbine.clusterNameExpression=aSGName</code>, which would get the cluster name from the AWS ASG name. Another example:</p><pre class="screen">turbine:
|
|
aggregator:
|
|
clusterConfig: SYSTEM,USER
|
|
appConfig: customers,stores,ui,admin
|
|
clusterNameExpression: metadata['cluster']</pre><p>In this case, the cluster name from 4 services is pulled from their metadata map, and is expected to have values that include "SYSTEM" and "USER".</p><p>To use the "default" cluster for all apps you need a string literal expression (with single quotes, and escaped with double quotes if it is in YAML as well):</p><pre class="screen">turbine:
|
|
appConfig: customers,stores
|
|
clusterNameExpression: "'default'"</pre><p>Spring Cloud provides a <code class="literal">spring-cloud-starter-turbine</code> that has all the dependencies you need to get a Turbine server running. Just create a Spring Boot application and annotate it with <code class="literal">@EnableTurbine</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>by default Spring Cloud allows Turbine to use the host and port to allow multiple processes per host, per cluster. If you want the native Netflix behaviour built into Turbine that does <span class="emphasis"><em>not</em></span> allow multiple processes per host, per cluster (the key to the instance id is the hostname), then set the property <code class="literal">turbine.combineHostPort=false</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_turbine_stream" href="#_turbine_stream"></a>15.3 Turbine Stream</h2></div></div></div><p>In some environments (e.g. in a PaaS setting), the classic Turbine model of pulling metrics from all the distributed Hystrix commands doesn’t work. In that case you might want to have your Hystrix commands push metrics to Turbine, and Spring Cloud enables that with messaging. All you need to do on the client is add a dependency to <code class="literal">spring-cloud-netflix-hystrix-stream</code> and the <code class="literal">spring-cloud-starter-stream-*</code> of your choice (see Spring Cloud Stream documentation for details on the brokers, and how to configure the client credentials, but it should work out of the box for a local broker).</p><p>On the server side Just create a Spring Boot application and annotate it with <code class="literal">@EnableTurbineStream</code> and by default it will come up on port 8989 (point your Hystrix dashboard to that port, any path). You can customize the port using either <code class="literal">server.port</code> or <code class="literal">turbine.stream.port</code>. If you have <code class="literal">spring-boot-starter-web</code> and <code class="literal">spring-boot-starter-actuator</code> on the classpath as well, then you can open up the Actuator endpoints on a separate port (with Tomcat by default) by providing a <code class="literal">management.port</code> which is different.</p><p>You can then point the Hystrix Dashboard to the Turbine Stream Server instead of individual Hystrix streams. If Turbine Stream is running on port 8989 on myhost, then put <code class="literal"><a class="link" href="http://myhost:8989" target="_top">http://myhost:8989</a></code> in the stream input field in the Hystrix Dashboard. Circuits will be prefixed by their respective serviceId, followed by a dot, then the circuit name.</p><p>Spring Cloud provides a <code class="literal">spring-cloud-starter-turbine-stream</code> that has all the dependencies you need to get a Turbine Stream server running - just add the Stream binder of your choice, e.g. <code class="literal">spring-cloud-starter-stream-rabbit</code>. You need Java 8 to run the app because it is Netty-based.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-ribbon" href="#spring-cloud-ribbon"></a>16. Client Side Load Balancer: Ribbon</h2></div></div></div><p>Ribbon is a client side load balancer which gives you a lot of control
|
|
over the behaviour of HTTP and TCP clients. Feign already uses Ribbon,
|
|
so if you are using <code class="literal">@FeignClient</code> then this section also applies.</p><p>A central concept in Ribbon is that of the named client. Each load
|
|
balancer is part of an ensemble of components that work together to
|
|
contact a remote server on demand, and the ensemble has a name that
|
|
you give it as an application developer (e.g. using the <code class="literal">@FeignClient</code>
|
|
annotation). Spring Cloud creates a new ensemble as an
|
|
<code class="literal">ApplicationContext</code> on demand for each named client using
|
|
<code class="literal">RibbonClientConfiguration</code>. This contains (amongst other things) an
|
|
<code class="literal">ILoadBalancer</code>, a <code class="literal">RestClient</code>, and a <code class="literal">ServerListFilter</code>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-ribbon-starter" href="#netflix-ribbon-starter"></a>16.1 How to Include Ribbon</h2></div></div></div><p>To include Ribbon in your project use the starter with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-starter-ribbon</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
|
|
for details on setting up your build system with the current Spring Cloud Release Train.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customizing_the_ribbon_client" href="#_customizing_the_ribbon_client"></a>16.2 Customizing the Ribbon Client</h2></div></div></div><p>You can configure some bits of a Ribbon client using external
|
|
properties in <code class="literal"><client>.ribbon.*</code>, which is no different than using
|
|
the Netflix APIs natively, except that you can use Spring Boot
|
|
configuration files. The native options can
|
|
be inspected as static fields in <code class="literal">CommonClientConfigKey</code> (part of
|
|
ribbon-core).</p><p>Spring Cloud also lets you take full control of the client by
|
|
declaring additional configuration (on top of the
|
|
<code class="literal">RibbonClientConfiguration</code>) using <code class="literal">@RibbonClient</code>. Example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RibbonClient(name = "foo", configuration = FooConfiguration.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TestConfiguration {
|
|
}</pre><p>In this case the client is composed from the components already in
|
|
<code class="literal">RibbonClientConfiguration</code> together with any in <code class="literal">FooConfiguration</code>
|
|
(where the latter generally will override the former).</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">FooConfiguration</code> has to be <code class="literal">@Configuration</code> but take
|
|
care that it is not in a <code class="literal">@ComponentScan</code> for the main application
|
|
context, otherwise it will be shared by all the <code class="literal">@RibbonClients</code>. If
|
|
you use <code class="literal">@ComponentScan</code> (or <code class="literal">@SpringBootApplication</code>) you need to
|
|
take steps to avoid it being included (for instance put it in a
|
|
separate, non-overlapping package, or specify the packages to scan
|
|
explicitly in the <code class="literal">@ComponentScan</code>).</p></td></tr></table></div><p>Spring Cloud Netflix provides the following beans by default for ribbon
|
|
(<code class="literal">BeanType</code> beanName: <code class="literal">ClassName</code>):</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">IClientConfig</code> ribbonClientConfig: <code class="literal">DefaultClientConfigImpl</code></li><li class="listitem"><code class="literal">IRule</code> ribbonRule: <code class="literal">ZoneAvoidanceRule</code></li><li class="listitem"><code class="literal">IPing</code> ribbonPing: <code class="literal">NoOpPing</code></li><li class="listitem"><code class="literal">ServerList<Server></code> ribbonServerList: <code class="literal">ConfigurationBasedServerList</code></li><li class="listitem"><code class="literal">ServerListFilter<Server></code> ribbonServerListFilter: <code class="literal">ZonePreferenceServerListFilter</code></li><li class="listitem"><code class="literal">ILoadBalancer</code> ribbonLoadBalancer: <code class="literal">ZoneAwareLoadBalancer</code></li><li class="listitem"><code class="literal">ServerListUpdater</code> ribbonServerListUpdater: <code class="literal">PollingServerListUpdater</code></li></ul></div><p>Creating a bean of one of those type and placing it in a <code class="literal">@RibbonClient</code>
|
|
configuration (such as <code class="literal">FooConfiguration</code> above) allows you to override each
|
|
one of the beans described. Example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> FooConfiguration {
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> IPing ribbonPing(IClientConfig config) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> PingUrl();
|
|
}
|
|
}</pre><p>This replaces the <code class="literal">NoOpPing</code> with <code class="literal">PingUrl</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customizing_the_ribbon_client_using_properties" href="#_customizing_the_ribbon_client_using_properties"></a>16.3 Customizing the Ribbon Client using properties</h2></div></div></div><p>Starting with version 1.2.0, Spring Cloud Netflix now supports customizing Ribbon clients using properties to be compatible with the <a class="link" href="https://github.com/Netflix/ribbon/wiki/Working-with-load-balancers#components-of-load-balancer" target="_top">Ribbon documentation</a>.</p><p>This allows you to change behavior at start up time in different environments.</p><p>The supported properties are listed below and should be prefixed by <code class="literal"><clientName>.ribbon.</code>:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">NFLoadBalancerClassName</code>: should implement <code class="literal">ILoadBalancer</code></li><li class="listitem"><code class="literal">NFLoadBalancerRuleClassName</code>: should implement <code class="literal">IRule</code></li><li class="listitem"><code class="literal">NFLoadBalancerPingClassName</code>: should implement <code class="literal">IPing</code></li><li class="listitem"><code class="literal">NIWSServerListClassName</code>: should implement <code class="literal">ServerList</code></li><li class="listitem"><code class="literal">NIWSServerListFilterClassName</code> should implement <code class="literal">ServerListFilter</code></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Classes defined in these properties have precedence over beans defined using <code class="literal">@RibbonClient(configuration=MyRibbonConfig.class)</code> and the defaults provided by Spring Cloud Netflix.</p></td></tr></table></div><p>To set the <code class="literal">IRule</code> for a service name <code class="literal">users</code> you could set the following:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">users:
|
|
ribbon:
|
|
NFLoadBalancerRuleClassName: com.netflix.loadbalancer.WeightedResponseTimeRule</pre><p>
|
|
</p><p>See the <a class="link" href="https://github.com/Netflix/ribbon/wiki/Working-with-load-balancers" target="_top">Ribbon documentation</a> for implementations provided by Ribbon.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_ribbon_with_eureka" href="#_using_ribbon_with_eureka"></a>16.4 Using Ribbon with Eureka</h2></div></div></div><p>When Eureka is used in conjunction with Ribbon (i.e., both are on the classpath) the <code class="literal">ribbonServerList</code>
|
|
is overridden with an extension of <code class="literal">DiscoveryEnabledNIWSServerList</code>
|
|
which populates the list of servers from Eureka. It also replaces the
|
|
<code class="literal">IPing</code> interface with <code class="literal">NIWSDiscoveryPing</code> which delegates to Eureka
|
|
to determine if a server is up. The <code class="literal">ServerList</code> that is installed by
|
|
default is a <code class="literal">DomainExtractingServerList</code> and the purpose of this is
|
|
to make physical metadata available to the load balancer without using
|
|
AWS AMI metadata (which is what Netflix relies on). By default the
|
|
server list will be constructed with "zone" information as provided in
|
|
the instance metadata (so on the remote clients set
|
|
<code class="literal">eureka.instance.metadataMap.zone</code>), and if that is missing it can use
|
|
the domain name from the server hostname as a proxy for zone (if the
|
|
flag <code class="literal">approximateZoneFromHostname</code> is set). Once the zone information
|
|
is available it can be used in a <code class="literal">ServerListFilter</code>. By default it
|
|
will be used to locate a server in the same zone as the client because
|
|
the default is a <code class="literal">ZonePreferenceServerListFilter</code>. The zone of the
|
|
client is determined the same way as the remote instances by default,
|
|
i.e. via <code class="literal">eureka.instance.metadataMap.zone</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The orthodox "archaius" way to set the client zone is via a
|
|
configuration property called "@zone", and Spring Cloud will use that
|
|
in preference to all other settings if it is available (note that the
|
|
key will have to be quoted in YAML configuration).</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If there is no other source of zone data then a guess is made
|
|
based on the client configuration (as opposed to the instance
|
|
configuration). We take <code class="literal">eureka.client.availabilityZones</code>, which is a
|
|
map from region name to a list of zones, and pull out the first zone
|
|
for the instance’s own region (i.e. the <code class="literal">eureka.client.region</code>, which
|
|
defaults to "us-east-1" for comatibility with native Netflix).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-ribbon-without-eureka" href="#spring-cloud-ribbon-without-eureka"></a>16.5 Example: How to Use Ribbon Without Eureka</h2></div></div></div><p>Eureka is a convenient way to abstract the discovery of remote servers
|
|
so you don’t have to hard code their URLs in clients, but if you
|
|
prefer not to use it, Ribbon and Feign are still quite
|
|
amenable. Suppose you have declared a <code class="literal">@RibbonClient</code> for "stores",
|
|
and Eureka is not in use (and not even on the classpath). The Ribbon
|
|
client defaults to a configured server list, and you can supply the
|
|
configuration like this</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">stores:
|
|
ribbon:
|
|
listOfServers: example.com,google.com</pre><p>
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_example_disable_eureka_use_in_ribbon" href="#_example_disable_eureka_use_in_ribbon"></a>16.6 Example: Disable Eureka use in Ribbon</h2></div></div></div><p>Setting the property <code class="literal">ribbon.eureka.enabled = false</code> will explicitly
|
|
disable the use of Eureka in Ribbon.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">ribbon:
|
|
eureka:
|
|
enabled: false</pre><p>
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_the_ribbon_api_directly" href="#_using_the_ribbon_api_directly"></a>16.7 Using the Ribbon API Directly</h2></div></div></div><p>You can also use the <code class="literal">LoadBalancerClient</code> directly. Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyClass {
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> LoadBalancerClient loadBalancer;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> doStuff() {
|
|
ServiceInstance instance = loadBalancer.choose(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stores"</span>);
|
|
URI storesUri = URI.create(String.format(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://%s:%s"</span>, instance.getHost(), instance.getPort()));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ... do something with the URI</span>
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ribbon-child-context-eager-load" href="#ribbon-child-context-eager-load"></a>16.8 Caching of Ribbon Configuration</h2></div></div></div><p>Each Ribbon named client has a corresponding child Application Context that Spring Cloud maintains, this application context is lazily loaded up on the first request to the named client.
|
|
This lazy loading behavior can be changed to instead eagerly load up these child Application contexts at startup by specifying the names of the Ribbon clients.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">ribbon:
|
|
eager-load:
|
|
enabled: true
|
|
clients: client1, client2, client3</pre><p>
|
|
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-feign" href="#spring-cloud-feign"></a>17. Declarative REST Client: Feign</h2></div></div></div><p><a class="link" href="https://github.com/Netflix/feign" target="_top">Feign</a> is a declarative web service client. It makes writing web service clients easier. To use Feign create an interface and annotate it. It has pluggable annotation support including Feign annotations and JAX-RS annotations. Feign also supports pluggable encoders and decoders. Spring Cloud adds support for Spring MVC annotations and for using the same <code class="literal">HttpMessageConverters</code> used by default in Spring Web. Spring Cloud integrates Ribbon and Eureka to provide a load balanced http client when using Feign.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-feign-starter" href="#netflix-feign-starter"></a>17.1 How to Include Feign</h2></div></div></div><p>To include Feign in your project use the starter with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-starter-feign</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
|
|
for details on setting up your build system with the current Spring Cloud Release Train.</p><p>Example spring boot app</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ComponentScan</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableEurekaClient</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableFeignClients</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(Application.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
|
|
}</pre><p><b>StoreClient.java. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@FeignClient("stores")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> StoreClient {
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/stores")</span></em>
|
|
List<Store> getStores();
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.POST, value = "/stores/{storeId}", consumes = "application/json")</span></em>
|
|
Store update(<em><span class="hl-annotation" style="color: gray">@PathVariable("storeId")</span></em> Long storeId, Store store);
|
|
}</pre><p>
|
|
</p><p>In the <code class="literal">@FeignClient</code> annotation the String value ("stores" above) is
|
|
an arbitrary client name, which is used to create a Ribbon load
|
|
balancer (see <a class="link" href="#spring-cloud-ribbon" title="16. Client Side Load Balancer: Ribbon">below for details of Ribbon
|
|
support</a>). You can also specify a URL using the <code class="literal">url</code> attribute
|
|
(absolute value or just a hostname). The name of the bean in the
|
|
application context is the fully qualified name of the interface.
|
|
To specify your own alias value you can use the <code class="literal">qualifier</code> value
|
|
of the <code class="literal">@FeignClient</code> annotation.</p><p>The Ribbon client above will want to discover the physical addresses
|
|
for the "stores" service. If your application is a Eureka client then
|
|
it will resolve the service in the Eureka service registry. If you
|
|
don’t want to use Eureka, you can simply configure a list of servers
|
|
in your external configuration (see
|
|
<a class="link" href="#spring-cloud-ribbon-without-eureka" title="16.5 Example: How to Use Ribbon Without Eureka">above for example</a>).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-feign-overriding-defaults" href="#spring-cloud-feign-overriding-defaults"></a>17.2 Overriding Feign Defaults</h2></div></div></div><p>A central concept in Spring Cloud’s Feign support is that of the named client. Each feign client is part of an ensemble of components that work together to contact a remote server on demand, and the ensemble has a name that you give it as an application developer using the <code class="literal">@FeignClient</code> annotation. Spring Cloud creates a new ensemble as an
|
|
<code class="literal">ApplicationContext</code> on demand for each named client using <code class="literal">FeignClientsConfiguration</code>. This contains (amongst other things) an <code class="literal">feign.Decoder</code>, a <code class="literal">feign.Encoder</code>, and a <code class="literal">feign.Contract</code>.</p><p>Spring Cloud lets you take full control of the feign client by declaring additional configuration (on top of the <code class="literal">FeignClientsConfiguration</code>) using <code class="literal">@FeignClient</code>. Example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@FeignClient(name = "stores", configuration = FooConfiguration.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> StoreClient {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//..</span>
|
|
}</pre><p>In this case the client is composed from the components already in <code class="literal">FeignClientsConfiguration</code> together with any in <code class="literal">FooConfiguration</code> (where the latter will override the former).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p><code class="literal">FooConfiguration</code> does not need to be annotated with <code class="literal">@Configuration</code>. However, if it is, then take care to exclude it from any <code class="literal">@ComponentScan</code> that would otherwise include this configuration as it will become the default source for <code class="literal">feign.Decoder</code>, <code class="literal">feign.Encoder</code>, <code class="literal">feign.Contract</code>, etc., when specified. This can be avoided by putting it in a separate, non-overlapping package from any <code class="literal">@ComponentScan</code> or <code class="literal">@SpringBootApplication</code>, or it can be explicitly excluded in <code class="literal">@ComponentScan</code>.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">serviceId</code> attribute is now deprecated in favor of the <code class="literal">name</code> attribute.</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Previously, using the <code class="literal">url</code> attribute, did not require the <code class="literal">name</code> attribute. Using <code class="literal">name</code> is now required.</p></td></tr></table></div><p>Placeholders are supported in the <code class="literal">name</code> and <code class="literal">url</code> attributes.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@FeignClient(name = "${feign.name}", url = "${feign.url}")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> StoreClient {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//..</span>
|
|
}</pre><p>Spring Cloud Netflix provides the following beans by default for feign (<code class="literal">BeanType</code> beanName: <code class="literal">ClassName</code>):</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">Decoder</code> feignDecoder: <code class="literal">ResponseEntityDecoder</code> (which wraps a <code class="literal">SpringDecoder</code>)</li><li class="listitem"><code class="literal">Encoder</code> feignEncoder: <code class="literal">SpringEncoder</code></li><li class="listitem"><code class="literal">Logger</code> feignLogger: <code class="literal">Slf4jLogger</code></li><li class="listitem"><code class="literal">Contract</code> feignContract: <code class="literal">SpringMvcContract</code></li><li class="listitem"><code class="literal">Feign.Builder</code> feignBuilder: <code class="literal">HystrixFeign.Builder</code></li><li class="listitem"><code class="literal">Client</code> feignClient: if Ribbon is enabled it is a <code class="literal">LoadBalancerFeignClient</code>, otherwise the default feign client is used.</li></ul></div><p>The OkHttpClient and ApacheHttpClient feign clients can be used by setting <code class="literal">feign.okhttp.enabled</code> or <code class="literal">feign.httpclient.enabled</code> to <code class="literal">true</code>, respectively, and having them on the classpath.</p><p>Spring Cloud Netflix <span class="emphasis"><em>does not</em></span> provide the following beans by default for feign, but still looks up beans of these types from the application context to create the feign client:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">Logger.Level</code></li><li class="listitem"><code class="literal">Retryer</code></li><li class="listitem"><code class="literal">ErrorDecoder</code></li><li class="listitem"><code class="literal">Request.Options</code></li><li class="listitem"><code class="literal">Collection<RequestInterceptor></code></li><li class="listitem"><code class="literal">SetterFactory</code></li></ul></div><p>Creating a bean of one of those type and placing it in a <code class="literal">@FeignClient</code> configuration (such as <code class="literal">FooConfiguration</code> above) allows you to override each one of the beans described. Example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> FooConfiguration {
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Contract feignContract() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> feign.Contract.Default();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> BasicAuthRequestInterceptor basicAuthRequestInterceptor() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BasicAuthRequestInterceptor(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"user"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"password"</span>);
|
|
}
|
|
}</pre><p>This replaces the <code class="literal">SpringMvcContract</code> with <code class="literal">feign.Contract.Default</code> and adds a <code class="literal">RequestInterceptor</code> to the collection of <code class="literal">RequestInterceptor</code>.</p><p>Default configurations can be specified in the <code class="literal">@EnableFeignClients</code> attribute <code class="literal">defaultConfiguration</code> in a similar manner as described above. The difference is that this configuration will apply to <span class="emphasis"><em>all</em></span> feign clients.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you need to use <code class="literal">ThreadLocal</code> bound variables in your <code class="literal">RequestInterceptor`s you will need to either set the
|
|
thread isolation strategy for Hystrix to `SEMAPHORE</code> or disable Hystrix in Feign.</p></td></tr></table></div><p>application.yml</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># To disable Hystrix in Feign</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">feign</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> hystrix</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># To set thread isolation to SEMAPHORE</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">hystrix</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> command</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> default</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> execution</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> isolation</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> strategy</span>: SEMAPHORE</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_creating_feign_clients_manually" href="#_creating_feign_clients_manually"></a>17.3 Creating Feign Clients Manually</h2></div></div></div><p>In some cases it might be necessary to customize your Feign Clients in a way that is not
|
|
possible using the methods above. In this case you can create Clients using the
|
|
<a class="link" href="https://github.com/OpenFeign/feign/#basics" target="_top">Feign Builder API</a>. Below is an example
|
|
which creates two Feign Clients with the same interface but configures each one with
|
|
a separate request interceptor.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Import(FeignClientsConfiguration.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> FooController {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> FooClient fooClient;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> FooClient adminClient;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> FooController(
|
|
Decoder decoder, Encoder encoder, Client client) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.fooClient = Feign.builder().client(client)
|
|
.encoder(encoder)
|
|
.decoder(decoder)
|
|
.requestInterceptor(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BasicAuthRequestInterceptor(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"user"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"user"</span>))
|
|
.target(FooClient.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://PROD-SVC"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.adminClient = Feign.builder().client(client)
|
|
.encoder(encoder)
|
|
.decoder(decoder)
|
|
.requestInterceptor(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BasicAuthRequestInterceptor(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"admin"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"admin"</span>))
|
|
.target(FooClient.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://PROD-SVC"</span>);
|
|
}
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>In the above example <code class="literal">FeignClientsConfiguration.class</code> is the default configuration
|
|
provided by Spring Cloud Netflix.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p><code class="literal">PROD-SVC</code> is the name of the service the Clients will be making requests to.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-feign-hystrix" href="#spring-cloud-feign-hystrix"></a>17.4 Feign Hystrix Support</h2></div></div></div><p>If Hystrix is on the classpath and <code class="literal">feign.hystrix.enabled=true</code>, Feign will wrap all methods with a circuit breaker. Returning a <code class="literal">com.netflix.hystrix.HystrixCommand</code> is also available. This lets you use reactive patterns (with a call to <code class="literal">.toObservable()</code> or <code class="literal">.observe()</code> or asynchronous use (with a call to <code class="literal">.queue()</code>).</p><p>To disable Hystrix support on a per-client basis create a vanilla <code class="literal">Feign.Builder</code> with the "prototype" scope, e.g.:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> FooConfiguration {
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Scope("prototype")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Feign.Builder feignBuilder() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Feign.builder();
|
|
}
|
|
}</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Prior to the Spring Cloud Dalston release, if Hystrix was on the classpath Feign would have wrapped
|
|
all methods in a circuit breaker by default. This default behavior was changed in Spring Cloud Dalston in
|
|
favor for an opt-in approach.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-feign-hystrix-fallback" href="#spring-cloud-feign-hystrix-fallback"></a>17.5 Feign Hystrix Fallbacks</h2></div></div></div><p>Hystrix supports the notion of a fallback: a default code path that is executed when they circuit is open or there is an error. To enable fallbacks for a given <code class="literal">@FeignClient</code> set the <code class="literal">fallback</code> attribute to the class name that implements the fallback. You also need to declare your implementation as a Spring bean.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@FeignClient(name = "hello", fallback = HystrixClientFallback.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> HystrixClient {
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/hello")</span></em>
|
|
Hello iFailSometimes();
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> HystrixClientFallback <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> HystrixClient {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Hello iFailSometimes() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Hello(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fallback"</span>);
|
|
}
|
|
}</pre><p>If one needs access to the cause that made the fallback trigger, one can use the <code class="literal">fallbackFactory</code> attribute inside <code class="literal">@FeignClient</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@FeignClient(name = "hello", fallbackFactory = HystrixClientFallbackFactory.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> HystrixClient {
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/hello")</span></em>
|
|
Hello iFailSometimes();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Component</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> HystrixClientFallbackFactory <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> FallbackFactory<HystrixClient> {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> HystrixClient create(Throwable cause) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HystrixClientWithFallBackFactory() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Hello iFailSometimes() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Hello(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fallback; reason was: "</span> + cause.getMessage());
|
|
}
|
|
};
|
|
}
|
|
}</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>There is a limitation with the implementation of fallbacks in Feign and how Hystrix fallbacks work. Fallbacks are currently not supported for methods that return <code class="literal">com.netflix.hystrix.HystrixCommand</code> and <code class="literal">rx.Observable</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_feign_and_literal_primary_literal" href="#_feign_and_literal_primary_literal"></a>17.6 Feign and <code class="literal">@Primary</code></h2></div></div></div><p>When using Feign with Hystrix fallbacks, there are multiple beans in the <code class="literal">ApplicationContext</code> of the same type. This will cause <code class="literal">@Autowired</code> to not work because there isn’t exactly one bean, or one marked as primary. To work around this, Spring Cloud Netflix marks all Feign instances as <code class="literal">@Primary</code>, so Spring Framework will know which bean to inject. In some cases, this may not be desirable. To turn off this behavior set the <code class="literal">primary</code> attribute of <code class="literal">@FeignClient</code> to false.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@FeignClient(name = "hello", primary = false)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> HelloClient {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// methods here</span>
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-feign-inheritance" href="#spring-cloud-feign-inheritance"></a>17.7 Feign Inheritance Support</h2></div></div></div><p>Feign supports boilerplate apis via single-inheritance interfaces.
|
|
This allows grouping common operations into convenient base interfaces.</p><p><b>UserService.java. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> UserService {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value ="/users/{id}")</span></em>
|
|
User getUser(<em><span class="hl-annotation" style="color: gray">@PathVariable("id")</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">long</span> id);
|
|
}</pre><p>
|
|
</p><p><b>UserResource.java. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> UserResource <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> UserService {
|
|
|
|
}</pre><p>
|
|
</p><p><b>UserClient.java. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> project.user;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@FeignClient("users")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> UserClient <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> UserService {
|
|
|
|
}</pre><p>
|
|
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>It is generally not advisable to share an interface between a
|
|
server and a client. It introduces tight coupling, and also actually
|
|
doesn’t work with Spring MVC in its current form (method parameter
|
|
mapping is not inherited).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_feign_request_response_compression" href="#_feign_request_response_compression"></a>17.8 Feign request/response compression</h2></div></div></div><p>You may consider enabling the request or response GZIP compression for your
|
|
Feign requests. You can do this by enabling one of the properties:</p><pre class="programlisting">feign.compression.request.enabled=true
|
|
feign.compression.response.enabled=true</pre><p>Feign request compression gives you settings similar to what you may set for your web server:</p><pre class="programlisting">feign.compression.request.enabled=true
|
|
feign.compression.request.mime-types=text/xml,application/xml,application/json
|
|
feign.compression.request.min-request-size=<span class="hl-number">2048</span></pre><p>These properties allow you to be selective about the compressed media types and minimum request threshold length.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_feign_logging" href="#_feign_logging"></a>17.9 Feign logging</h2></div></div></div><p>A logger is created for each Feign client created. By default the name of the logger is the full class name of the interface used to create the Feign client. Feign logging only responds to the <code class="literal">DEBUG</code> level.</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">logging.level.project.user.UserClient</span>: DEBUG</pre><p>
|
|
</p><p>The <code class="literal">Logger.Level</code> object that you may configure per client, tells Feign how much to log. Choices are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">NONE</code>, No logging (<span class="strong"><strong>DEFAULT</strong></span>).</li><li class="listitem"><code class="literal">BASIC</code>, Log only the request method and URL and the response status code and execution time.</li><li class="listitem"><code class="literal">HEADERS</code>, Log the basic information along with request and response headers.</li><li class="listitem"><code class="literal">FULL</code>, Log the headers, body, and metadata for both requests and responses.</li></ul></div><p>For example, the following would set the <code class="literal">Logger.Level</code> to <code class="literal">FULL</code>:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> FooConfiguration {
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
Logger.Level feignLoggerLevel() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Logger.Level.FULL;
|
|
}
|
|
}</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_external_configuration_archaius" href="#_external_configuration_archaius"></a>18. External Configuration: Archaius</h2></div></div></div><p><a class="link" href="https://github.com/Netflix/archaius" target="_top">Archaius</a> is the Netflix client side configuration library. It is the library used by all of the Netflix OSS components for configuration. Archaius is an extension of the <a class="link" href="http://commons.apache.org/proper/commons-configuration" target="_top">Apache Commons Configuration</a> project. It allows updates to configuration by either polling a source for changes or for a source to push changes to the client. Archaius uses Dynamic<Type>Property classes as handles to properties.</p><p><b>Archaius Example. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ArchaiusTest {
|
|
DynamicStringProperty myprop = DynamicPropertyFactory
|
|
.getInstance()
|
|
.getStringProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"my.prop"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> doSomething() {
|
|
OtherClass.someMethod(myprop.get());
|
|
}
|
|
}</pre><p>
|
|
</p><p>Archaius has its own set of configuration files and loading priorities. Spring applications should generally not use Archaius directly, but the need to configure the Netflix tools natively remains. Spring Cloud has a Spring Environment Bridge so Archaius can read properties from the Spring Environment. This allows Spring Boot projects to use the normal configuration toolchain, while allowing them to configure the Netflix tools, for the most part, as documented.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_router_and_filter_zuul" href="#_router_and_filter_zuul"></a>19. Router and Filter: Zuul</h2></div></div></div><p>Routing in an integral part of a microservice architecture. For example, <code class="literal">/</code> may be mapped to your web application, <code class="literal">/api/users</code> is mapped to the user service and <code class="literal">/api/shop</code> is mapped to the shop service. <a class="link" href="https://github.com/Netflix/zuul" target="_top">Zuul</a> is a JVM based router and server side load balancer by Netflix.</p><p><a class="link" href="http://www.slideshare.net/MikeyCohen1/edge-architecture-ieee-international-conference-on-cloud-engineering-32240146/27" target="_top">Netflix uses Zuul</a> for the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Authentication</li><li class="listitem">Insights</li><li class="listitem">Stress Testing</li><li class="listitem">Canary Testing</li><li class="listitem">Dynamic Routing</li><li class="listitem">Service Migration</li><li class="listitem">Load Shedding</li><li class="listitem">Security</li><li class="listitem">Static Response handling</li><li class="listitem">Active/Active traffic management</li></ul></div><p>Zuul’s rule engine allows rules and filters to be written in essentially any JVM language, with built in support for Java and Groovy.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The configuration property <code class="literal">zuul.max.host.connections</code> has been replaced by two new properties, <code class="literal">zuul.host.maxTotalConnections</code> and <code class="literal">zuul.host.maxPerRouteConnections</code> which default to 200 and 20 respectively.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Default Hystrix isolation pattern (ExecutionIsolationStrategy) for all routes is SEMAPHORE. <code class="literal">zuul.ribbonIsolationStrategy</code> can be changed to THREAD if this isolation pattern is preferred.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-zuul-starter" href="#netflix-zuul-starter"></a>19.1 How to Include Zuul</h2></div></div></div><p>To include Zuul in your project use the starter with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-starter-zuul</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a>
|
|
for details on setting up your build system with the current Spring Cloud Release Train.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-zuul-reverse-proxy" href="#netflix-zuul-reverse-proxy"></a>19.2 Embedded Zuul Reverse Proxy</h2></div></div></div><p>Spring Cloud has created an embedded Zuul proxy to ease the
|
|
development of a very common use case where a UI application wants to
|
|
proxy calls to one or more back end services. This feature is useful
|
|
for a user interface to proxy to the backend services it requires,
|
|
avoiding the need to manage CORS and authentication concerns
|
|
independently for all the backends.</p><p>To enable it, annotate a Spring Boot main class with
|
|
<code class="literal">@EnableZuulProxy</code>, and this forwards local calls to the appropriate
|
|
service. By convention, a service with the ID "users", will
|
|
receive requests from the proxy located at <code class="literal">/users</code> (with the prefix
|
|
stripped). The proxy uses Ribbon to locate an instance to forward to
|
|
via discovery, and all requests are executed in a
|
|
<a class="link" href="#hystrix-fallbacks-for-routes" title="19.12 Providing Hystrix Fallbacks For Routes">hystrix command</a>, so
|
|
failures will show up in Hystrix metrics, and once the circuit is open
|
|
the proxy will not try to contact the service.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the Zuul starter does not include a discovery client, so for
|
|
routes based on service IDs you need to provide one of those
|
|
on the classpath as well (e.g. Eureka is one choice).</p></td></tr></table></div><p>To skip having a service automatically added, set
|
|
<code class="literal">zuul.ignored-services</code> to a list of service id patterns. If a service
|
|
matches a pattern that is ignored, but also included in the explicitly
|
|
configured routes map, then it will be unignored. Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ignoredServices</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'*'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>: /myusers/**</pre><p>
|
|
</p><p>In this example, all services are ignored <span class="strong"><strong>except</strong></span> "users".</p><p>To augment or change
|
|
the proxy routes, you can add external configuration like the
|
|
following:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>: /myusers/**</pre><p>
|
|
</p><p>This means that http calls to "/myusers" get forwarded to the "users"
|
|
service (for example "/myusers/101" is forwarded to "/101").</p><p>To get more fine-grained control over a route you can specify the path
|
|
and the serviceId independently:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /myusers/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> serviceId</span>: users_service</pre><p>
|
|
</p><p>This means that http calls to "/myusers" get forwarded to the
|
|
"users_service" service. The route has to have a "path" which can be
|
|
specified as an ant-style pattern, so "/myusers/*" only matches one
|
|
level, but "/myusers/**" matches hierarchically.</p><p>The location of the backend can be specified as either a "serviceId"
|
|
(for a service from discovery) or a "url" (for a physical location), e.g.</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /myusers/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: http://example.com/users_service</pre><p>
|
|
</p><p>These simple url-routes don’t get executed as a <code class="literal">HystrixCommand</code> nor can you loadbalance multiple URLs with Ribbon.
|
|
To achieve this, specify a service-route and configure a Ribbon client for the
|
|
serviceId (this currently requires disabling Eureka support in Ribbon:
|
|
see <a class="link" href="#spring-cloud-ribbon-without-eureka" title="16.5 Example: How to Use Ribbon Without Eureka">above for more information</a>), e.g.</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /myusers/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> serviceId</span>: users
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">ribbon</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> eureka</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ribbon</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> listOfServers</span>: example.com,google.com</pre><p>
|
|
</p><p>You can provide convention between serviceId and routes using
|
|
regexmapper. It uses regular expression named groups to extract
|
|
variables from serviceId and inject them into a route pattern.</p><p><b>ApplicationConfiguration.java. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> PatternServiceRouteMapper serviceRouteMapper() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> PatternServiceRouteMapper(
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"(?<name>^.+)-(?<version>v.+$)"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${version}/${name}"</span>);
|
|
}</pre><p>
|
|
</p><p>This means that a serviceId "myusers-v1" will be mapped to route
|
|
"/v1/myusers/**". Any regular expression is accepted but all named
|
|
groups must be present in both servicePattern and routePattern. If
|
|
servicePattern does not match a serviceId, the default behavior is
|
|
used. In the example above, a serviceId "myusers" will be mapped to route
|
|
"/myusers/**" (no version detected) This feature is disable by
|
|
default and only applies to discovered services.</p><p>To add a prefix to all mappings, set <code class="literal">zuul.prefix</code> to a value, such as
|
|
<code class="literal">/api</code>. The proxy prefix is stripped from the request before the
|
|
request is forwarded by default (switch this behaviour off with
|
|
<code class="literal">zuul.stripPrefix=false</code>). You can also switch off the stripping of
|
|
the service-specific prefix from individual routes, e.g.</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /myusers/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> stripPrefix</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span></pre><p>
|
|
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p><code class="literal">zuul.stripPrefix</code> only applies to the prefix set in <code class="literal">zuul.prefix</code>. It does not have any effect on prefixes
|
|
defined within a given route’s <code class="literal">path</code>.</p></td></tr></table></div><p>In this example, requests to "/myusers/101" will be forwarded to "/myusers/101" on the "users" service.</p><p>The <code class="literal">zuul.routes</code> entries actually bind to an object of type <code class="literal">ZuulProperties</code>. If you
|
|
look at the properties of that object you will see that it also has a "retryable" flag.
|
|
Set that flag to "true" to have the Ribbon client automatically retry failed requests
|
|
(and if you need to you can modify the parameters of the retry operations using
|
|
the Ribbon client configuration).</p><p>The <code class="literal">X-Forwarded-Host</code> header is added to the forwarded requests by
|
|
default. To turn it off set <code class="literal">zuul.addProxyHeaders = false</code>. The
|
|
prefix path is stripped by default, and the request to the backend
|
|
picks up a header "X-Forwarded-Prefix" ("/myusers" in the examples
|
|
above).</p><p>An application with <code class="literal">@EnableZuulProxy</code> could act as a standalone
|
|
server if you set a default route ("/"), for example <code class="literal">zuul.route.home:
|
|
/</code> would route all traffic (i.e. "/**") to the "home" service.</p><p>If more fine-grained ignoring is needed, you can specify specific patterns to ignore.
|
|
These patterns are evaluated at the start of the route location process, which
|
|
means prefixes should be included in the pattern to warrant a match. Ignored patterns
|
|
span all services and supersede any other route specification.</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ignoredPatterns</span>: /**/admin/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>: /myusers/**</pre><p>
|
|
</p><p>This means that all calls such as "/myusers/101" will be forwarded to "/101" on the "users" service.
|
|
But calls including "/admin/" will not resolve.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>If you need your routes to have their order preserved you need to use a YAML
|
|
file as the ordering will be lost using a properties file. For example:</p></td></tr></table></div><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /myusers/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> legacy</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /**</pre><p>
|
|
</p><p>If you were to use a properties file, the <code class="literal">legacy</code> path may end up in front of the <code class="literal">users</code>
|
|
path rendering the <code class="literal">users</code> path unreachable.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_zuul_http_client" href="#_zuul_http_client"></a>19.3 Zuul Http Client</h2></div></div></div><p>The default HTTP client used by zuul is now backed by the Apache HTTP Client instead of the
|
|
deprecated Ribbon <code class="literal">RestClient</code>. To use <code class="literal">RestClient</code> or to use the <code class="literal">okhttp3.OkHttpClient</code> set
|
|
<code class="literal">ribbon.restclient.enabled=true</code> or <code class="literal">ribbon.okhttp.enabled=true</code> respectively.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_cookies_and_sensitive_headers" href="#_cookies_and_sensitive_headers"></a>19.4 Cookies and Sensitive Headers</h2></div></div></div><p>It’s OK to share headers between services in the same system, but you
|
|
probably don’t want sensitive headers leaking downstream into external
|
|
servers. You can specify a list of ignored headers as part of the
|
|
route configuration. Cookies play a special role because they have
|
|
well-defined semantics in browsers, and they are always to be treated
|
|
as sensitive. If the consumer of your proxy is a browser, then cookies
|
|
for downstream services also cause problems for the user because they
|
|
all get jumbled up (all downstream services look like they come from
|
|
the same place).</p><p>If you are careful with the design of your services, for example if
|
|
only one of the downstream services sets cookies, then you might be
|
|
able to let them flow from the backend all the way up to the
|
|
caller. Also, if your proxy sets cookies and all your back end
|
|
services are part of the same system, it can be natural to simply
|
|
share them (and for instance use Spring Session to link them up to some
|
|
shared state). Other than that, any cookies that get set by downstream
|
|
services are likely to be not very useful to the caller, so it is
|
|
recommended that you make (at least) "Set-Cookie" and "Cookie" into
|
|
sensitive headers for routes that are not part of your domain. Even
|
|
for routes that <span class="strong"><strong>are</strong></span> part of your domain, try to think carefully
|
|
about what it means before allowing cookies to flow between them and
|
|
the proxy.</p><p>The sensitive headers can be configured as a comma-separated list per
|
|
route, e.g.</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /myusers/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> sensitiveHeaders</span>: Cookie,Set-Cookie,Authorization
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: https://downstream</pre><p>
|
|
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>this is the default value for <code class="literal">sensitiveHeaders</code>, so you don’t
|
|
need to set it unless you want it to be different. N.B. this is new in
|
|
Spring Cloud Netflix 1.1 (in 1.0 the user had no control over headers
|
|
and all cookies flow in both directions).</p></td></tr></table></div><p>The <code class="literal">sensitiveHeaders</code> are a blacklist and the default is not empty,
|
|
so to make Zuul send all headers (except the "ignored" ones) you would
|
|
have to explicitly set it to the empty list. This is necessary if you
|
|
want to pass cookie or authorization headers to your back end. Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> users</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /myusers/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> sensitiveHeaders</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: https://downstream</pre><p>
|
|
</p><p>Sensitive headers can also be set globally by setting <code class="literal">zuul.sensitiveHeaders</code>. If <code class="literal">sensitiveHeaders</code> is set on a route, this will override the global <code class="literal">sensitiveHeaders</code> setting.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_ignored_headers" href="#_ignored_headers"></a>19.5 Ignored Headers</h2></div></div></div><p>In addition to the per-route sensitive headers, you can set a global
|
|
value for <code class="literal">zuul.ignoredHeaders</code> for values that should be discarded
|
|
(both request and response) during interactions with downstream
|
|
services. By default these are empty, if Spring Security is not on the
|
|
classpath, and otherwise they are initialized to a set of well-known
|
|
"security" headers (e.g. involving caching) as specified by Spring
|
|
Security. The assumption in this case is that the downstream services
|
|
might add these headers too, and we want the values from the proxy.
|
|
To not discard these well known security headers in case Spring Security is on the classpath you can set <code class="literal">zuul.ignoreSecurityHeaders</code> to <code class="literal">false</code>. This can be useful if you disabled the HTTP Security response headers in Spring Security and want the values provided by downstream services</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_the_routes_endpoint" href="#_the_routes_endpoint"></a>19.6 The Routes Endpoint</h2></div></div></div><p>If you are using <code class="literal">@EnableZuulProxy</code> with tha Spring Boot Actuator you
|
|
will enable (by default) an additional endpoint, available via HTTP as
|
|
<code class="literal">/routes</code>. A GET to this endpoint will return a list of the mapped
|
|
routes. A POST will force a refresh of the existing routes (e.g. in
|
|
case there have been changes in the service catalog). You can disable
|
|
this endpoint by setting <code class="literal">endpoints.routes.enabled</code> to <code class="literal">false</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the routes should respond automatically to changes in the
|
|
service catalog, but the POST to /routes is a way to force the change
|
|
to happen immediately.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_strangulation_patterns_and_local_forwards" href="#_strangulation_patterns_and_local_forwards"></a>19.7 Strangulation Patterns and Local Forwards</h2></div></div></div><p>A common pattern when migrating an existing application or API is to
|
|
"strangle" old endpoints, slowly replacing them with different
|
|
implementations. The Zuul proxy is a useful tool for this because you
|
|
can use it to handle all traffic from clients of the old endpoints,
|
|
but redirect some of the requests to new ones.</p><p>Example configuration:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> first</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /first/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: http://first.example.com
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> second</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /second/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: forward:/second
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> third</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /third/**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: forward:/<span class="hl-number">3</span>rd
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> legacy</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> path</span>: /**
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: http://legacy.example.com</pre><p>
|
|
</p><p>In this example we are strangling the "legacy" app which is mapped to
|
|
all requests that do not match one of the other patterns. Paths in
|
|
<code class="literal">/first/**</code> have been extracted into a new service with an external
|
|
URL. And paths in <code class="literal">/second/**</code> are forwarded so they can be handled
|
|
locally, e.g. with a normal Spring <code class="literal">@RequestMapping</code>. Paths in
|
|
<code class="literal">/third/**</code> are also forwarded, but with a different prefix
|
|
(i.e. <code class="literal">/third/foo</code> is forwarded to <code class="literal">/3rd/foo</code>).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The ignored patterns aren’t completely ignored, they just
|
|
aren’t handled by the proxy (so they are also effectively forwarded
|
|
locally).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_uploading_files_through_zuul" href="#_uploading_files_through_zuul"></a>19.8 Uploading Files through Zuul</h2></div></div></div><p>If you <code class="literal">@EnableZuulProxy</code> you can use the proxy paths to
|
|
upload files and it should just work as long as the files
|
|
are small. For large files there is an alternative path
|
|
which bypasses the Spring <code class="literal">DispatcherServlet</code> (to
|
|
avoid multipart processing) in "/zuul/*". I.e. if
|
|
<code class="literal">zuul.routes.customers=/customers/**</code> then you can
|
|
POST large files to "/zuul/customers/*". The servlet
|
|
path is externalized via <code class="literal">zuul.servletPath</code>. Extremely
|
|
large files will also require elevated timeout settings
|
|
if the proxy route takes you through a Ribbon load
|
|
balancer, e.g.</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">hystrix.command.default.execution.isolation.thread.timeoutInMilliseconds</span>: <span class="hl-number">60000</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">ribbon</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ConnectTimeout</span>: <span class="hl-number">3000</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ReadTimeout</span>: <span class="hl-number">60000</span></pre><p>
|
|
</p><p>Note that for streaming to work with large files, you need to use chunked encoding in the request (which some browsers
|
|
do not do by default). E.g. on the command line:</p><pre class="screen">$ curl -v -H "Transfer-Encoding: chunked" \
|
|
-F "file=@mylarge.iso" localhost:9999/zuul/simple/file</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_query_string_encoding" href="#_query_string_encoding"></a>19.9 Query String Encoding</h2></div></div></div><p>When processing the incoming request, query params are decoded so they can be available for possible modifications in
|
|
Zuul filters. They are then re-encoded when building the backend request in the route filters. The result
|
|
can be different than the original input if it was encoded using Javascript’s <code class="literal">encodeURIComponent()</code> method for example.
|
|
While this causes no issues in most cases, some web servers can be picky with the encoding of complex query string.</p><p>To force the original encoding of the query string, it is possible to pass a special flag to <code class="literal">ZuulProperties</code> so
|
|
that the query string is taken as is with the <code class="literal">HttpServletRequest::getQueryString</code> method :</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> forceOriginalQueryStringEncoding</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre><p>
|
|
</p><p><span class="strong"><strong>Note:</strong></span> This special flag only works with <code class="literal">SimpleHostRoutingFilter</code> and you loose the ability to easily override
|
|
query parameters with <code class="literal">RequestContext.getCurrentContext().setRequestQueryParams(someOverriddenParameters)</code> since
|
|
the query string is now fetched directly on the original <code class="literal">HttpServletRequest</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_plain_embedded_zuul" href="#_plain_embedded_zuul"></a>19.10 Plain Embedded Zuul</h2></div></div></div><p>You can also run a Zuul server without the proxying, or switch on parts of the proxying platform selectively, if you
|
|
use <code class="literal">@EnableZuulServer</code> (instead of <code class="literal">@EnableZuulProxy</code>). Any beans that you add to the application of type <code class="literal">ZuulFilter</code>
|
|
will be installed automatically, as they are with <code class="literal">@EnableZuulProxy</code>, but without any of the proxy filters being added
|
|
automatically.</p><p>In this case the routes into the Zuul server are still specified by
|
|
configuring "zuul.routes.*", but there is no service
|
|
discovery and no proxying, so the "serviceId" and "url" settings are
|
|
ignored. For example:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> api</span>: /api/**</pre><p>
|
|
</p><p>maps all paths in "/api/**" to the Zuul filter chain.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_disable_zuul_filters" href="#_disable_zuul_filters"></a>19.11 Disable Zuul Filters</h2></div></div></div><p>Zuul for Spring Cloud comes with a number of <code class="literal">ZuulFilter</code> beans enabled by default
|
|
in both proxy and server mode. See <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters" target="_top">the zuul filters package</a> for the
|
|
possible filters that are enabled. If you want to disable one, simply set
|
|
<code class="literal">zuul.<SimpleClassName>.<filterType>.disable=true</code>. By convention, the package after
|
|
<code class="literal">filters</code> is the Zuul filter type. For example to disable
|
|
<code class="literal">org.springframework.cloud.netflix.zuul.filters.post.SendResponseFilter</code> set
|
|
<code class="literal">zuul.SendResponseFilter.post.disable=true</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="hystrix-fallbacks-for-routes" href="#hystrix-fallbacks-for-routes"></a>19.12 Providing Hystrix Fallbacks For Routes</h2></div></div></div><p>When a circuit for a given route in Zuul is tripped you can provide a fallback response
|
|
by creating a bean of type <code class="literal">ZuulFallbackProvider</code>. Within this bean you need to specify
|
|
the route ID the fallback is for and provide a <code class="literal">ClientHttpResponse</code> to return
|
|
as a fallback. Here is a very simple <code class="literal">ZuulFallbackProvider</code> implementation.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyFallbackProvider <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> ZuulFallbackProvider {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String getRoute() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"customers"</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ClientHttpResponse fallbackResponse() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ClientHttpResponse() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> HttpStatus getStatusCode() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> HttpStatus.OK;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> getRawStatusCode() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span class="hl-number">200</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String getStatusText() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"OK"</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> close() {
|
|
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> InputStream getBody() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ByteArrayInputStream(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fallback"</span>.getBytes());
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> HttpHeaders getHeaders() {
|
|
HttpHeaders headers = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpHeaders();
|
|
headers.setContentType(MediaType.APPLICATION_JSON);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> headers;
|
|
}
|
|
};
|
|
}
|
|
}</pre><p>And here is what the route configuration would look like.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">zuul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> customers</span>: /customers/**</pre><p>If you would like to provide a default fallback for all routes than you can create a bean of
|
|
type <code class="literal">ZuulFallbackProvider</code> and have the <code class="literal">getRoute</code> method return <code class="literal">*</code> or <code class="literal">null</code>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyFallbackProvider <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> ZuulFallbackProvider {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String getRoute() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"*"</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ClientHttpResponse fallbackResponse() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ClientHttpResponse() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> HttpStatus getStatusCode() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> HttpStatus.OK;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> getRawStatusCode() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span class="hl-number">200</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String getStatusText() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"OK"</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> close() {
|
|
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> InputStream getBody() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ByteArrayInputStream(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fallback"</span>.getBytes());
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> HttpHeaders getHeaders() {
|
|
HttpHeaders headers = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpHeaders();
|
|
headers.setContentType(MediaType.APPLICATION_JSON);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> headers;
|
|
}
|
|
};
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zuul-developer-guide" href="#zuul-developer-guide"></a>19.13 Zuul Developer Guide</h2></div></div></div><p>For a general overview of how Zuul works, please see <a class="link" href="https://github.com/Netflix/zuul/wiki/How-it-Works" target="_top">the Zuul Wiki</a>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_the_zuul_servlet" href="#_the_zuul_servlet"></a>19.13.1 The Zuul Servlet</h3></div></div></div><p>Zuul is implemented as a Servlet. For the general cases, Zuul is embedded into the Spring Dispatch mechanism. This allows Spring MVC to be in control of the routing. In this case, Zuul is configured to buffer requests. If there is a need to go through Zuul without buffering requests (e.g. for large file uploads), the Servlet is also installed outside of the Spring Dispatcher. By default, this is located at <code class="literal">/zuul</code>. This path can be changed with the <code class="literal">zuul.servlet-path</code> property.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_zuul_requestcontext" href="#_zuul_requestcontext"></a>19.13.2 Zuul RequestContext</h3></div></div></div><p>To pass information between filters, Zuul uses a <a class="link" href="https://github.com/Netflix/zuul/blob/1.x/zuul-core/src/main/java/com/netflix/zuul/context/RequestContext.java" target="_top"><code class="literal">RequestContext</code></a>. Its data is held in a <code class="literal">ThreadLocal</code> specific to each request. Information about where to route requests, errors and the actual <code class="literal">HttpServletRequest</code> and <code class="literal">HttpServletResponse</code> are stored there. The <code class="literal">RequestContext</code> extends <code class="literal">ConcurrentHashMap</code>, so anything can be stored in the context. <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/support/FilterConstants.java" target="_top"><code class="literal">FilterConstants</code></a> contains the keys that are used by the filters installed by Spring Cloud Netflix (more on these later).</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__literal_enablezuulproxy_literal_vs_literal_enablezuulserver_literal" href="#__literal_enablezuulproxy_literal_vs_literal_enablezuulserver_literal"></a>19.13.3 <code class="literal">@EnableZuulProxy</code> vs. <code class="literal">@EnableZuulServer</code></h3></div></div></div><p>Spring Cloud Netflix installs a number of filters based on which annotation was used to enable Zuul. <code class="literal">@EnableZuulProxy</code> is a superset of <code class="literal">@EnableZuulServer</code>. In other words, <code class="literal">@EnableZuulProxy</code> contains all filters installed by <code class="literal">@EnableZuulServer</code>. The additional filters in the "proxy" enable routing functionality. If you want a "blank" Zuul, you should use <code class="literal">@EnableZuulServer</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__literal_enablezuulserver_literal_filters" href="#__literal_enablezuulserver_literal_filters"></a>19.13.4 <code class="literal">@EnableZuulServer</code> Filters</h3></div></div></div><p>Creates a <code class="literal">SimpleRouteLocator</code> that loads route definitions from Spring Boot configuration files.</p><p>The following filters are installed (as normal Spring Beans):</p><p>Pre filters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">ServletDetectionFilter</code>: Detects if the request is through the Spring Dispatcher. Sets boolean with key <code class="literal">FilterConstants.IS_DISPATCHER_SERVLET_REQUEST_KEY</code>.</li><li class="listitem"><code class="literal">FormBodyWrapperFilter</code>: Parses form data and reencodes it for downstream requests.</li><li class="listitem"><code class="literal">DebugFilter</code>: if the <code class="literal">debug</code> request parameter is set, this filter sets <code class="literal">RequestContext.setDebugRouting()</code> and <code class="literal">RequestContext.setDebugRequest()</code> to true.</li></ul></div><p>Route filters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">SendForwardFilter</code>: This filter forwards requests using the Servlet <code class="literal">RequestDispatcher</code>. The forwarding location is stored in the <code class="literal">RequestContext</code> attribute <code class="literal">FilterConstants.FORWARD_TO_KEY</code>. This is useful for forwarding to endpoints in the current application.</li></ul></div><p>Post filters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">SendResponseFilter</code>: Writes responses from proxied requests to the current response.</li></ul></div><p>Error filters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">SendErrorFilter</code>: Forwards to /error (by default) if <code class="literal">RequestContext.getThrowable()</code> is not null. The default forwarding path (<code class="literal">/error</code>) can be changed by setting the <code class="literal">error.path</code> property.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__literal_enablezuulproxy_literal_filters" href="#__literal_enablezuulproxy_literal_filters"></a>19.13.5 <code class="literal">@EnableZuulProxy</code> Filters</h3></div></div></div><p>Creates a <code class="literal">DiscoveryClientRouteLocator</code> that loads route definitions from a <code class="literal">DiscoveryClient</code> (like Eureka), as well as from properties. A route is created for each <code class="literal">serviceId</code> from the <code class="literal">DiscoveryClient</code>. As new services are added, the routes will be refreshed.</p><p>In addition to the filters described above, the following filters are installed (as normal Spring Beans):</p><p>Pre filters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">PreDecorationFilter</code>: This filter determines where and how to route based on the supplied <code class="literal">RouteLocator</code>. It also sets various proxy-related headers for downstream requests.</li></ul></div><p>Route filters:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara"><code class="literal">RibbonRoutingFilter</code>: This filter uses Ribbon, Hystrix and pluggable HTTP clients to send requests. Service ids are found in the <code class="literal">RequestContext</code> attribute <code class="literal">FilterConstants.SERVICE_ID_KEY</code>. This filter can use different HTTP clients. They are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">Apache <code class="literal">HttpClient</code>. This is the default client.</li><li class="listitem">Squareup <code class="literal">OkHttpClient</code> v3. This is enabled by having the <code class="literal">com.squareup.okhttp3:okhttp</code> library on the classpath and setting <code class="literal">ribbon.okhttp.enabled=true</code>.</li><li class="listitem">Netflix Ribbon HTTP client. This is enabled by setting <code class="literal">ribbon.restclient.enabled=true</code>. This client has limitations, such as it doesn’t support the PATCH method, but also has built-in retry.</li></ul></div></li><li class="listitem"><code class="literal">SimpleHostRoutingFilter</code>: This filter sends requests to predetermined URLs via an Apache HttpClient. URLs are found in <code class="literal">RequestContext.getRouteHost()</code>.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_custom_zuul_filter_examples" href="#_custom_zuul_filter_examples"></a>19.13.6 Custom Zuul Filter examples</h3></div></div></div><p>Most of the following "How to Write" examples below are included <a class="link" href="https://github.com/spring-cloud-samples/sample-zuul-filters" target="_top">Sample Zuul Filters</a> project. There are also examples of manipulating the request or response body in that repository.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_how_to_write_a_pre_filter" href="#_how_to_write_a_pre_filter"></a>19.13.7 How to Write a Pre Filter</h3></div></div></div><p>Pre filters are used to set up data in the <code class="literal">RequestContext</code> for use in filters downstream. The main use case is to set information required for route filters.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> QueryParamPreFilter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ZuulFilter {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> filterOrder() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> PRE_DECORATION_FILTER_ORDER - <span class="hl-number">1</span>; <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// run before PreDecoration</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String filterType() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> PRE_TYPE;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> shouldFilter() {
|
|
RequestContext ctx = RequestContext.getCurrentContext();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> !ctx.containsKey(FORWARD_TO_KEY) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// a filter has already forwarded</span>
|
|
&& !ctx.containsKey(SERVICE_ID_KEY); <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// a filter has already determined serviceId</span>
|
|
}
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Object run() {
|
|
RequestContext ctx = RequestContext.getCurrentContext();
|
|
HttpServletRequest request = ctx.getRequest();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (request.getParameter(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>) != null) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// put the serviceId in `RequestContext`</span>
|
|
ctx.put(SERVICE_ID_KEY, request.getParameter(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>));
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> null;
|
|
}
|
|
}</pre><p>The filter above populates <code class="literal">SERVICE_ID_KEY</code> from the <code class="literal">foo</code> request parameter. In reality, it’s not a good idea to do that kind of direct mapping, but the service id should be looked up from the value of <code class="literal">foo</code> instead.</p><p>Now that <code class="literal">SERVICE_ID_KEY</code> is populated, <code class="literal">PreDecorationFilter</code> won’t run and <code class="literal">RibbonRoutingFilter</code> will. If you wanted to route to a full URL instead, call <code class="literal">ctx.setRouteHost(url)</code> instead.</p><p>To modify the path that routing filters will forward to, set the <code class="literal">REQUEST_URI_KEY</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_how_to_write_a_route_filter" href="#_how_to_write_a_route_filter"></a>19.13.8 How to Write a Route Filter</h3></div></div></div><p>Route filters are run after pre filters and are used to make requests to other services. Much of the work here is to translate request and response data to and from the client required model.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> OkHttpRoutingFilter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ZuulFilter {
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> ProxyRequestHelper helper;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String filterType() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> ROUTE_TYPE;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> filterOrder() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> SIMPLE_HOST_ROUTING_FILTER_ORDER - <span class="hl-number">1</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> shouldFilter() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> RequestContext.getCurrentContext().getRouteHost() != null
|
|
&& RequestContext.getCurrentContext().sendZuulResponse();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Object run() {
|
|
OkHttpClient httpClient = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> OkHttpClient.Builder()
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// customize</span>
|
|
.build();
|
|
|
|
RequestContext context = RequestContext.getCurrentContext();
|
|
HttpServletRequest request = context.getRequest();
|
|
|
|
String method = request.getMethod();
|
|
|
|
String uri = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.helper.buildZuulRequestURI(request);
|
|
|
|
Headers.Builder headers = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Headers.Builder();
|
|
Enumeration<String> headerNames = request.getHeaderNames();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">while</span> (headerNames.hasMoreElements()) {
|
|
String name = headerNames.nextElement();
|
|
Enumeration<String> values = request.getHeaders(name);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">while</span> (values.hasMoreElements()) {
|
|
String value = values.nextElement();
|
|
headers.add(name, value);
|
|
}
|
|
}
|
|
|
|
InputStream inputStream = request.getInputStream();
|
|
|
|
RequestBody requestBody = null;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (inputStream != null && HttpMethod.permitsRequestBody(method)) {
|
|
MediaType mediaType = null;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>) != null) {
|
|
mediaType = MediaType.parse(headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>));
|
|
}
|
|
requestBody = RequestBody.create(mediaType, StreamUtils.copyToByteArray(inputStream));
|
|
}
|
|
|
|
Request.Builder builder = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Request.Builder()
|
|
.headers(headers.build())
|
|
.url(uri)
|
|
.method(method, requestBody);
|
|
|
|
Response response = httpClient.newCall(builder.build()).execute();
|
|
|
|
LinkedMultiValueMap<String, String> responseHeaders = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> LinkedMultiValueMap<>();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> (Map.Entry<String, List<String>> entry : response.headers().toMultimap().entrySet()) {
|
|
responseHeaders.put(entry.getKey(), entry.getValue());
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.helper.setResponse(response.code(), response.body().byteStream(),
|
|
responseHeaders);
|
|
context.setRouteHost(null); <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// prevent SimpleHostRoutingFilter from running</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> null;
|
|
}
|
|
}</pre><p>The above filter translates Servlet request information into OkHttp3 request information, executes an HTTP request, then translates OkHttp3 reponse information to the Servlet response. WARNING: this filter might have bugs and not function correctly.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_how_to_write_a_post_filter" href="#_how_to_write_a_post_filter"></a>19.13.9 How to Write a Post Filter</h3></div></div></div><p>Post filters typically manipulate the response. In the filter below, we add a random <code class="literal">UUID</code> as the <code class="literal">X-Foo</code> header. Other manipulations, such as transforming the response body, are much more complex and compute-intensive.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> AddResponseHeaderFilter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ZuulFilter {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String filterType() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> POST_TYPE;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> filterOrder() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> SEND_RESPONSE_FILTER_ORDER - <span class="hl-number">1</span>;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> shouldFilter() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> true;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Object run() {
|
|
RequestContext context = RequestContext.getCurrentContext();
|
|
HttpServletResponse servletResponse = context.getResponse();
|
|
servletResponse.addHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"X-Foo"</span>, UUID.randomUUID().toString());
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> null;
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_how_zuul_errors_work" href="#_how_zuul_errors_work"></a>19.13.10 How Zuul Errors Work</h3></div></div></div><p>If an exception is thrown during any portion of the Zuul filter lifecycle, the error filters are executed. The <code class="literal">SendErrorFilter</code> is only run if <code class="literal">RequestContext.getThrowable()</code> is not <code class="literal">null</code>. It then sets specific <code class="literal">javax.servlet.error.*</code> attributes in the request and forwards the request to the Spring Boot error page.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_zuul_eager_application_context_loading" href="#_zuul_eager_application_context_loading"></a>19.13.11 Zuul Eager Application Context Loading</h3></div></div></div><p>Zuul internally uses Ribbon for calling the remote url’s and Ribbon clients are by default lazily loaded up by Spring Cloud on first call.
|
|
This behavior can be changed for Zuul using the following configuration and will result in the child Ribbon related Application contexts being eagerly loaded up at application startup time.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">zuul:
|
|
ribbon:
|
|
eager-load:
|
|
enabled: true</pre><p>
|
|
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_polyglot_support_with_sidecar" href="#_polyglot_support_with_sidecar"></a>20. Polyglot support with Sidecar</h2></div></div></div><p>Do you have non-jvm languages you want to take advantage of Eureka, Ribbon and
|
|
Config Server? The Spring Cloud Netflix Sidecar was inspired by
|
|
<a class="link" href="https://github.com/Netflix/Prana" target="_top">Netflix Prana</a>. It includes a simple http api
|
|
to get all of the instances (ie host and port) for a given service. You can
|
|
also proxy service calls through an embedded Zuul proxy which gets its route
|
|
entries from Eureka. The Spring Cloud Config Server can be accessed directly
|
|
via host lookup or through the Zuul Proxy. The non-jvm app should implement
|
|
a health check so the Sidecar can report to eureka if the app is up or down.</p><p>To include Sidecar in your project use the dependency with group <code class="literal">org.springframework.cloud</code>
|
|
and artifact id <code class="literal">spring-cloud-netflix-sidecar</code>.</p><p>To enable the Sidecar, create a Spring Boot application with <code class="literal">@EnableSidecar</code>.
|
|
This annotation includes <code class="literal">@EnableCircuitBreaker</code>, <code class="literal">@EnableDiscoveryClient</code>,
|
|
and <code class="literal">@EnableZuulProxy</code>. Run the resulting application on the same host as the
|
|
non-jvm application.</p><p>To configure the side car add <code class="literal">sidecar.port</code> and <code class="literal">sidecar.health-uri</code> to <code class="literal">application.yml</code>.
|
|
The <code class="literal">sidecar.port</code> property is the port the non-jvm app is listening on. This
|
|
is so the Sidecar can properly register the app with Eureka. The <code class="literal">sidecar.health-uri</code>
|
|
is a uri accessible on the non-jvm app that mimicks a Spring Boot health
|
|
indicator. It should return a json document like the following:</p><p><b>health-uri-document. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"UP"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
|
|
</p><p>Here is an example application.yml for a Sidecar application:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> port</span>: <span class="hl-number">5678</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> application</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> name</span>: sidecar
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">sidecar</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> port</span>: <span class="hl-number">8000</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> health-uri</span>: http://localhost:<span class="hl-number">8000</span>/health.json</pre><p>
|
|
</p><p>The api for the <code class="literal">DiscoveryClient.getInstances()</code> method is <code class="literal">/hosts/{serviceId}</code>.
|
|
Here is an example response for <code class="literal">/hosts/customers</code> that returns two instances on
|
|
different hosts. This api is accessible to the non-jvm app (if the sidecar is
|
|
on port 5678) at <code class="literal"><a class="link" href="http://localhost:5678/hosts/{serviceId}" target="_top">http://localhost:5678/hosts/{serviceId}</a></code>.</p><p><b>/hosts/customers. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"host"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"myhost"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"port"</span>: <span class="hl-number">9000</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"uri"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://myhost:9000"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"serviceId"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"CUSTOMERS"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secure"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"host"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"myhost2"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"port"</span>: <span class="hl-number">9000</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"uri"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://myhost2:9000"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"serviceId"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"CUSTOMERS"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secure"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span></pre><p>
|
|
</p><p>The Zuul proxy automatically adds routes for each service known in eureka to
|
|
<code class="literal">/<serviceId></code>, so the customers service is available at <code class="literal">/customers</code>. The
|
|
Non-jvm app can access the customer service via <code class="literal"><a class="link" href="http://localhost:5678/customers" target="_top">http://localhost:5678/customers</a></code>
|
|
(assuming the sidecar is listening on port 5678).</p><p>If the Config Server is registered with Eureka, non-jvm application can access
|
|
it via the Zuul proxy. If the serviceId of the ConfigServer is <code class="literal">configserver</code>
|
|
and the Sidecar is on port 5678, then it can be accessed at
|
|
<a class="link" href="http://localhost:5678/configserver" target="_top">http://localhost:5678/configserver</a></p><p>Non-jvm app can take advantage of the Config Server’s ability to return YAML
|
|
documents. For example, a call to <a class="link" href="http://sidecar.local.spring.io:5678/configserver/default-master.yml" target="_top">http://sidecar.local.spring.io:5678/configserver/default-master.yml</a>
|
|
might result in a YAML document like the following</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">eureka</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> client</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> serviceUrl</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> defaultZone</span>: http://localhost:<span class="hl-number">8761</span>/eureka/
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: password
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">info</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> description</span>: Spring Cloud Samples
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: https://github.com/spring-cloud-samples</pre></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="netflix-rxjava-springmvc" href="#netflix-rxjava-springmvc"></a>21. RxJava with Spring MVC</h2></div></div></div><p>Spring Cloud Netflix includes <a class="link" href="https://github.com/ReactiveX/RxJava" target="_top">RxJava</a>.</p><div class="blockquote"><blockquote class="blockquote"><p>RxJava is a Java VM implementation of <a class="link" href="http://reactivex.io/" target="_top">Reactive Extensions</a>: a library for composing asynchronous and event-based programs by using observable sequences.</p></blockquote></div><p>Spring Cloud Netflix provides support for returning <code class="literal">rx.Single</code> objects from Spring MVC Controllers. It also supports using <code class="literal">rx.Observable</code> objects for <a class="link" href="https://en.wikipedia.org/wiki/Server-sent_events" target="_top">Server-sent events (SSE)</a>. This can be very convenient if your internal APIs are already built using RxJava (see <a class="xref" href="#spring-cloud-feign-hystrix" title="17.4 Feign Hystrix Support">Section 17.4, “Feign Hystrix Support”</a> for examples).</p><p>Here are some examples of using <code class="literal">rx.Single</code>:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/single")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Single<String> single() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Single.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"single value"</span>);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/singleWithResponse")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ResponseEntity<Single<String>> singleWithResponse() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ResponseEntity<>(Single.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"single value"</span>),
|
|
HttpStatus.NOT_FOUND);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/singleCreatedWithResponse")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Single<ResponseEntity<String>> singleOuterWithResponse() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Single.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ResponseEntity<>(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"single value"</span>, HttpStatus.CREATED));
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/throw")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Single<Object> error() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Single.error(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> RuntimeException(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Unexpected"</span>));
|
|
}</pre><p>If you have an <code class="literal">Observable</code>, rather than a single, you can use <code class="literal">.toSingle()</code> or <code class="literal">.toList().toSingle()</code>. Here are some examples:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/single")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Single<String> single() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Observable.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"single value"</span>).toSingle();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/multiple")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Single<List<String>> multiple() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Observable.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"multiple"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"values"</span>).toList().toSingle();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/responseWithObservable")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ResponseEntity<Single<String>> responseWithObservable() {
|
|
|
|
Observable<String> observable = Observable.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"single value"</span>);
|
|
HttpHeaders headers = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpHeaders();
|
|
headers.setContentType(APPLICATION_JSON_UTF8);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ResponseEntity<>(observable.toSingle(), headers, HttpStatus.CREATED);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/timeout")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Observable<String> timeout() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Observable.timer(<span class="hl-number">1</span>, TimeUnit.MINUTES).map(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Func1<Long, String>() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String call(Long aLong) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"single value"</span>;
|
|
}
|
|
});
|
|
}</pre><p>If you have a streaming endpoint and client, SSE could be an option. To convert <code class="literal">rx.Observable</code> to a Spring <code class="literal">SseEmitter</code> use <code class="literal">RxResponse.sse()</code>. Here are some examples:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/sse")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> SseEmitter single() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> RxResponse.sse(Observable.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"single value"</span>));
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/messages")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> SseEmitter messages() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> RxResponse.sse(Observable.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"message 1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"message 2"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"message 3"</span>));
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(method = RequestMethod.GET, value = "/events")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> SseEmitter event() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> RxResponse.sse(APPLICATION_JSON_UTF8,
|
|
Observable.just(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> EventDto(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Spring io"</span>, getDate(<span class="hl-number">2016</span>, <span class="hl-number">5</span>, <span class="hl-number">19</span>)),
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> EventDto(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"SpringOnePlatform"</span>, getDate(<span class="hl-number">2016</span>, <span class="hl-number">8</span>, <span class="hl-number">1</span>))));
|
|
}</pre></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="netflix-metrics" href="#netflix-metrics"></a>22. Metrics: Spectator, Servo, and Atlas</h2></div></div></div><p>When used together, Spectator/Servo and Atlas provide a near real-time operational insight platform.</p><p>Spectator and Servo are Netflix’s metrics collection libraries. Atlas is a Netflix metrics backend to manage dimensional time series data.</p><p>Servo served Netflix for several years and is still usable, but is gradually being phased out in favor of Spectator, which is only designed to work with Java 8. Spring Cloud Netflix provides support for both, but Java 8 based applications are encouraged to use Spectator.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_dimensional_vs_hierarchical_metrics" href="#_dimensional_vs_hierarchical_metrics"></a>22.1 Dimensional vs. Hierarchical Metrics</h2></div></div></div><p>Spring Boot Actuator metrics are hierarchical and metrics are separated only by name. These names often follow a naming convention that embeds key/value attribute pairs (dimensions) into the name separated by periods. Consider the following metrics for two endpoints, root and star-star:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"counter.status.200.root"</span>: <span class="hl-number">20</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"counter.status.400.root"</span>: <span class="hl-number">3</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"counter.status.200.star-star"</span>: <span class="hl-number">5</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>The first metric gives us a normalized count of successful requests against the root endpoint per unit of time. But what if the system had 20 endpoints and you want to get a count of successful requests against all the endpoints? Some hierarchical metrics backends would allow you to specify a wild card such as <code class="literal">counter.status.200.*</code> that would read all 20 metrics and aggregate the results. Alternatively, you could provide a <code class="literal">HandlerInterceptorAdapter</code> that intercepts and records a metric like <code class="literal">counter.status.200.all</code> for all successful requests irrespective of the endpoint, but now you must write 20+1 different metrics. Similarly if you want to know the total number of successful requests for all endpoints in the service, you could specify a wild card such as <code class="literal">counter.status.2*.*</code>.</p><p>Even in the presence of wildcarding support on a hierarchical metrics backend, naming consistency can be difficult. Specifically the position of these tags in the name string can slip with time, breaking queries. For example, suppose we add an additional dimension to the hierarchical metrics above for HTTP method. Then <code class="literal">counter.status.200.root</code> becomes <code class="literal">counter.status.200.method.get.root</code>, etc. Our <code class="literal">counter.status.200.*</code> suddenly no longer has the same semantic meaning. Furthermore, if the new dimension is not applied uniformly across the codebase, certain queries may become impossible. This can quickly get out of hand.</p><p>Netflix metrics are tagged (a.k.a. dimensional). Each metric has a name, but this single named metric can contain multiple statistics and 'tag' key/value pairs that allows more querying flexibility. In fact, the statistics themselves are recorded in a special tag.</p><p>Recorded with Netflix Servo or Spectator, a timer for the root endpoint described above contains 4 statistics per status code, where the count statistic is identical to Spring Boot Actuator’s counter. In the event that we have encountered an HTTP 200 and 400 thus far, there will be 8 available data points:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=200,stastic=count)"</span>: <span class="hl-number">20</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=200,stastic=max)"</span>: <span class="hl-number">0.7265630630000001</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=200,stastic=totalOfSquares)"</span>: <span class="hl-number">0.04759702862580789</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=200,stastic=totalTime)"</span>: <span class="hl-number">0.2093076914666667</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=400,stastic=count)"</span>: <span class="hl-number">1</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=400,stastic=max)"</span>: <span class="hl-number">0</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=400,stastic=totalOfSquares)"</span>: <span class="hl-number">0</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root(status=400,stastic=totalTime)"</span>: <span class="hl-number">0</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_default_metrics_collection" href="#_default_metrics_collection"></a>22.2 Default Metrics Collection</h2></div></div></div><p>Without any additional dependencies or configuration, a Spring Cloud based service will autoconfigure a Servo <code class="literal">MonitorRegistry</code> and begin collecting metrics on every Spring MVC request. By default, a Servo timer with the name <code class="literal">rest</code> will be recorded for each MVC request which is tagged with:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">HTTP method</li><li class="listitem">HTTP status (e.g. 200, 400, 500)</li><li class="listitem">URI (or "root" if the URI is empty), sanitized for Atlas</li><li class="listitem">The exception class name, if the request handler threw an exception</li><li class="listitem">The caller, if a request header with a key matching <code class="literal">netflix.metrics.rest.callerHeader</code> is set on the request. There is no default key for <code class="literal">netflix.metrics.rest.callerHeader</code>. You must add it to your application properties if you wish to collect caller information.</li></ol></div><p>Set the <code class="literal">netflix.metrics.rest.metricName</code> property to change the name of the metric from <code class="literal">rest</code> to a name you provide.</p><p>If Spring AOP is enabled and <code class="literal">org.aspectj:aspectjweaver</code> is present on your runtime classpath, Spring Cloud will also collect metrics on every client call made with <code class="literal">RestTemplate</code>. A Servo timer with the name of <code class="literal">restclient</code> will be recorded for each MVC request which is tagged with:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">HTTP method</li><li class="listitem">HTTP status (e.g. 200, 400, 500), "CLIENT_ERROR" if the response returned null, or "IO_ERROR" if an <code class="literal">IOException</code> occurred during the execution of the <code class="literal">RestTemplate</code> method</li><li class="listitem">URI, sanitized for Atlas</li><li class="listitem">Client name</li></ol></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Avoid using hardcoded url parameters within <code class="literal">RestTemplate</code>. When targeting dynamic endpoints use URL variables. This will avoid potential "GC Overhead Limit Reached" issues where <code class="literal">ServoMonitorCache</code> treats each url as a unique key.</p></td></tr></table></div><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// recommended</span>
|
|
String orderid = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"1"</span>;
|
|
restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://testeurekabrixtonclient/orders/{orderid}"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, orderid)
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// avoid</span>
|
|
restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://testeurekabrixtonclient/orders/1"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-metrics-spectator" href="#netflix-metrics-spectator"></a>22.3 Metrics Collection: Spectator</h2></div></div></div><p>To enable Spectator metrics, include a dependency on <code class="literal">spring-boot-starter-spectator</code>:</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-spectator<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>In Spectator parlance, a meter is a named, typed, and tagged configuration and a metric represents the value of a given meter at a point in time. Spectator meters are created and controlled by a registry, which currently has several different implementations. Spectator provides 4 meter types: counter, timer, gauge, and distribution summary.</p><p>Spring Cloud Spectator integration configures an injectable <code class="literal">com.netflix.spectator.api.Registry</code> instance for you. Specifically, it configures a <code class="literal">ServoRegistry</code> instance in order to unify the collection of REST metrics and the exporting of metrics to the Atlas backend under a single Servo API. Practically, this means that your code may use a mixture of Servo monitors and Spectator meters and both will be scooped up by Spring Boot Actuator <code class="literal">MetricReader</code> instances and both will be shipped to the Atlas backend.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spectator_counter" href="#_spectator_counter"></a>22.3.1 Spectator Counter</h3></div></div></div><p>A counter is used to measure the rate at which some event is occurring.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// create a counter with a name and a set of tags</span>
|
|
Counter counter = registry.counter(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"counterName"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagKey1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagValue1"</span>, ...);
|
|
counter.increment(); <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// increment when an event occurs</span>
|
|
counter.increment(<span class="hl-number">10</span>); <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// increment by a discrete amount</span></pre><p>The counter records a single time-normalized statistic.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spectator_timer" href="#_spectator_timer"></a>22.3.2 Spectator Timer</h3></div></div></div><p>A timer is used to measure how long some event is taking. Spring Cloud automatically records timers for Spring MVC requests and conditionally <code class="literal">RestTemplate</code> requests, which can later be used to create dashboards for request related metrics like latency:</p><div class="figure"><a name="d0e5502" href="#d0e5502"></a><p class="title"><b>Figure 22.1. Request Latency</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/RequestLatency.png" alt="RequestLatency"></div></div></div><br class="figure-break"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// create a timer with a name and a set of tags</span>
|
|
Timer timer = registry.timer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timerName"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagKey1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagValue1"</span>, ...);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// execute an operation and time it at the same time</span>
|
|
T result = timer.record(() -> fooReturnsT());
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// alternatively, if you must manually record the time</span>
|
|
Long start = System.nanoTime();
|
|
T result = fooReturnsT();
|
|
timer.record(System.nanoTime() - start, TimeUnit.NANOSECONDS);</pre><p>The timer simultaneously records 4 statistics: count, max, totalOfSquares, and totalTime. The count statistic will always match the single normalized value provided by a counter if you had called <code class="literal">increment()</code> once on the counter for each time you recorded a timing, so it is rarely necessary to count and time separately for a single operation.</p><p>For <a class="link" href="https://github.com/Netflix/spectator/wiki/Timer-Usage#longtasktimer" target="_top">long running operations</a>, Spectator provides a special <code class="literal">LongTaskTimer</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spectator_gauge" href="#_spectator_gauge"></a>22.3.3 Spectator Gauge</h3></div></div></div><p>Gauges are used to determine some current value like the size of a queue or number of threads in a running state. Since gauges are sampled, they provide no information about how these values fluctuate between samples.</p><p>The normal use of a gauge involves registering the gauge once in initialization with an id, a reference to the object to be sampled, and a function to get or compute a numeric value based on the object. The reference to the object is passed in separately and the Spectator registry will keep a weak reference to the object. If the object is garbage collected, then Spectator will automatically drop the registration. See <a class="link" href="https://github.com/Netflix/spectator/wiki/Gauge-Usage#using-lambda" target="_top">the note</a> in Spectator’s documentation about potential memory leaks if this API is misused.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the registry will automatically sample this gauge periodically</span>
|
|
registry.gauge(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"gaugeName"</span>, pool, Pool::numberOfRunningThreads);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// manually sample a value in code at periodic intervals -- last resort!</span>
|
|
registry.gauge(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"gaugeName"</span>, Arrays.asList(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagKey1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagValue1"</span>, ...), <span class="hl-number">1000</span>);</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spectator_distribution_summaries" href="#_spectator_distribution_summaries"></a>22.3.4 Spectator Distribution Summaries</h3></div></div></div><p>A distribution summary is used to track the distribution of events. It is similar to a timer, but more general in that the size does not have to be a period of time. For example, a distribution summary could be used to measure the payload sizes of requests hitting a server.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the registry will automatically sample this gauge periodically</span>
|
|
DistributionSummary ds = registry.distributionSummary(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"dsName"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagKey1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagValue1"</span>, ...);
|
|
ds.record(request.sizeInBytes());</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-metrics-servo" href="#netflix-metrics-servo"></a>22.4 Metrics Collection: Servo</h2></div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>If your code is compiled on Java 8, please use Spectator instead of Servo as Spectator is destined to replace Servo entirely in the long term.</p></td></tr></table></div><p>In Servo parlance, a monitor is a named, typed, and tagged configuration and a metric represents the value of a given monitor at a point in time. Servo monitors are logically equivalent to Spectator meters. Servo monitors are created and controlled by a <code class="literal">MonitorRegistry</code>. In spite of the above warning, Servo does have a <a class="link" href="https://github.com/Netflix/servo/wiki/Getting-Started" target="_top">wider array</a> of monitor options than Spectator has meters.</p><p>Spring Cloud integration configures an injectable <code class="literal">com.netflix.servo.MonitorRegistry</code> instance for you. Once you have created the appropriate <code class="literal">Monitor</code> type in Servo, the process of recording data is wholly similar to Spectator.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_creating_servo_monitors" href="#_creating_servo_monitors"></a>22.4.1 Creating Servo Monitors</h3></div></div></div><p>If you are using the Servo <code class="literal">MonitorRegistry</code> instance provided by Spring Cloud (specifically, an instance of <code class="literal">DefaultMonitorRegistry</code>), Servo provides convenience classes for retrieving <a class="link" href="https://github.com/Netflix/spectator/wiki/Servo-Comparison#dynamiccounter" target="_top">counters</a> and <a class="link" href="https://github.com/Netflix/spectator/wiki/Servo-Comparison#dynamictimer" target="_top">timers</a>. These convenience classes ensure that only one <code class="literal">Monitor</code> is registered for each unique combination of name and tags.</p><p>To manually create a Monitor type in Servo, especially for the more exotic monitor types for which convenience methods are not provided, instantiate the appropriate type by providing a <code class="literal">MonitorConfig</code> instance:</p><pre class="programlisting">MonitorConfig config = MonitorConfig.builder(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timerName"</span>).withTag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagKey1"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tagValue1"</span>).build();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// somewhere we should cache this Monitor by MonitorConfig</span>
|
|
Timer timer = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BasicTimer(config);
|
|
monitorRegistry.register(timer);</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="netflix-metrics-atlas" href="#netflix-metrics-atlas"></a>22.5 Metrics Backend: Atlas</h2></div></div></div><p>Atlas was developed by Netflix to manage dimensional time series data for near real-time operational insight. Atlas features in-memory data storage, allowing it to gather and report very large numbers of metrics, very quickly.</p><p>Atlas captures operational intelligence. Whereas business intelligence is data gathered for analyzing trends over time, operational intelligence provides a picture of what is currently happening within a system.</p><p>Spring Cloud provides a <code class="literal">spring-cloud-starter-atlas</code> that has all the dependencies you need. Then just annotate your Spring Boot application with <code class="literal">@EnableAtlas</code> and provide a location for your running Atlas server with the <code class="literal">netflix.atlas.uri</code> property.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_global_tags" href="#_global_tags"></a>22.5.1 Global tags</h3></div></div></div><p>Spring Cloud enables you to add tags to every metric sent to the Atlas backend. Global tags can be used to separate metrics by application name, environment, region, etc.</p><p>Each bean implementing <code class="literal">AtlasTagProvider</code> will contribute to the global tag list:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
AtlasTagProvider atlasCommonTags(
|
|
<em><span class="hl-annotation" style="color: gray">@Value("${spring.application.name}")</span></em> String appName) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> () -> Collections.singletonMap(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"app"</span>, appName);
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_using_atlas" href="#_using_atlas"></a>22.5.2 Using Atlas</h3></div></div></div><p>To bootstrap a in-memory standalone Atlas instance:</p><pre class="programlisting">$ curl -LO https://github.com/Netflix/atlas/releases/download/v1.<span class="hl-number">4.2</span>/atlas-<span class="hl-number">1.4</span>.<span class="hl-number">2</span>-standalone.jar
|
|
$ java -jar atlas-<span class="hl-number">1.4</span>.<span class="hl-number">2</span>-standalone.jar</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>An Atlas standalone node running on an r3.2xlarge (61GB RAM) can handle roughly 2 million metrics per minute for a given 6 hour window.</p></td></tr></table></div><p>Once running and you have collected a handful of metrics, verify that your setup is correct by listing tags on the Atlas server:</p><pre class="programlisting">$ curl http://ATLAS/api/v1/tags</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>After executing several requests against your service, you can gather some very basic information on the request latency of every request by pasting the following url in your browser: <code class="literal"><a class="link" href="http://ATLAS/api/v1/graph?q=name,rest,:eq,:avg" target="_top">http://ATLAS/api/v1/graph?q=name,rest,:eq,:avg</a></code></p></td></tr></table></div><p>The Atlas wiki contains a <a class="link" href="https://github.com/Netflix/atlas/wiki/Single-Line" target="_top">compilation of sample queries</a> for various scenarios.</p><p>Make sure to check out the <a class="link" href="https://github.com/Netflix/atlas/wiki/Alerting-Philosophy" target="_top">alerting philosophy</a> and docs on using <a class="link" href="https://github.com/Netflix/atlas/wiki/DES" target="_top">double exponential smoothing</a> to generate dynamic alert thresholds.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="retrying-failed-requests" href="#retrying-failed-requests"></a>22.6 Retrying Failed Requests</h2></div></div></div><p>Spring Cloud Netflix offers a variety of ways to make HTTP requests. You can use a load balanced
|
|
<code class="literal">RestTemplate</code>, Ribbon, or Feign. No matter how you choose to your HTTP requests, there is always
|
|
a chance the request may fail. When a request fails you may want to have the request retried
|
|
automatically. To accomplish this when using Sping Cloud Netflix you need to include
|
|
<a class="link" href="https://github.com/spring-projects/spring-retry" target="_top">Spring Retry</a> on your application’s classpath.
|
|
When Spring Retry is present load balanced <code class="literal">RestTemplates</code>, Feign, and Zuul will automatically
|
|
retry any failed requests (assuming you configuration allows it to).</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configuration" href="#_configuration"></a>22.6.1 Configuration</h3></div></div></div><p>Anytime Ribbon is used with Spring Retry you can control the retry functionality by configuring
|
|
certain Ribbon properties. The properties you can use are
|
|
<code class="literal">client.ribbon.MaxAutoRetries</code>, <code class="literal">client.ribbon.MaxAutoRetriesNextServer</code>, and
|
|
<code class="literal">client.ribbon.OkToRetryOnAllOperations</code>. See the <a class="link" href="https://github.com/Netflix/ribbon/wiki/Getting-Started#the-properties-file-sample-clientproperties" target="_top">Ribbon documentation</a>
|
|
for a description of what there properties do.</p><p>In addition you may want to retry requests when certain status codes are returned in the
|
|
response. You can list the response codes you would like the Ribbon client to retry using the
|
|
property <code class="literal">clientName.ribbon.retryableStatusCodes</code>. For example</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">clientName</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ribbon</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> retryableStatusCodes</span>: <span class="hl-number">404</span>,<span class="hl-number">502</span></pre><p>You can also create a bean of type <code class="literal">LoadBalancedRetryPolicy</code> and implement the <code class="literal">retryableStatusCode</code>
|
|
method to determine whether you want to retry a request given the status code.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_zuul" href="#_zuul"></a>22.6.2 Zuul</h3></div></div></div><p>You can turn off Zuul’s retry functionality by setting <code class="literal">zuul.retryable</code> to <code class="literal">false</code>. You
|
|
can also disable retry functionality on route by route basis by setting
|
|
<code class="literal">zuul.routes.routename.retryable</code> to <code class="literal">false</code>.</p></div></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_stream" href="#_spring_cloud_stream"></a>Part IV. Spring Cloud Stream</h1></div></div></div><div class="partintro"><div></div><p>This section goes into more detail about how you can work with Spring Cloud Stream.
|
|
It covers topics such as creating and running stream applications.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_introducing_spring_cloud_stream" href="#_introducing_spring_cloud_stream"></a>23. Introducing Spring Cloud Stream</h2></div></div></div><p>Spring Cloud Stream is a framework for building message-driven microservice applications.
|
|
Spring Cloud Stream builds upon Spring Boot to create standalone, production-grade Spring applications, and uses Spring Integration to provide connectivity to message brokers.
|
|
It provides opinionated configuration of middleware from several vendors, introducing the concepts of persistent publish-subscribe semantics, consumer groups, and partitions.</p><p>You can add the <code class="literal">@EnableBinding</code> annotation to your application to get immediate connectivity to a message broker, and you can add <code class="literal">@StreamListener</code> to a method to cause it to receive events for stream processing.
|
|
The following is a simple sink application which receives external messages.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> VoteRecordingSinkApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(VoteRecordingSinkApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(Sink.INPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> processVote(Vote vote) {
|
|
votingService.recordVote(vote);
|
|
}
|
|
}</pre><p>The <code class="literal">@EnableBinding</code> annotation takes one or more interfaces as parameters (in this case, the parameter is a single <code class="literal">Sink</code> interface).
|
|
An interface declares input and/or output channels.
|
|
Spring Cloud Stream provides the interfaces <code class="literal">Source</code>, <code class="literal">Sink</code>, and <code class="literal">Processor</code>; you can also define your own interfaces.</p><p>The following is the definition of the <code class="literal">Sink</code> interface:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Sink {
|
|
String INPUT = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"input"</span>;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Input(Sink.INPUT)</span></em>
|
|
SubscribableChannel input();
|
|
}</pre><p>The <code class="literal">@Input</code> annotation identifies an <span class="emphasis"><em>input channel</em></span>, through which received messages enter the application; the <code class="literal">@Output</code> annotation identifies an <span class="emphasis"><em>output channel</em></span>, through which published messages leave the application.
|
|
The <code class="literal">@Input</code> and <code class="literal">@Output</code> annotations can take a channel name as a parameter; if a name is not provided, the name of the annotated method will be used.</p><p>Spring Cloud Stream will create an implementation of the interface for you.
|
|
You can use this in the application by autowiring it, as in the following example of a test case.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringJUnit4ClassRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringApplicationConfiguration(classes = VoteRecordingSinkApplication.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@WebAppConfiguration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@DirtiesContext</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> StreamApplicationTests {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> Sink sink;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> contextLoads() {
|
|
assertNotNull(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.sink.input());
|
|
}
|
|
}</pre></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_main_concepts" href="#_main_concepts"></a>24. Main Concepts</h2></div></div></div><p>Spring Cloud Stream provides a number of abstractions and primitives that simplify the writing of message-driven microservice applications.
|
|
This section gives an overview of the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Spring Cloud Stream’s application model</li><li class="listitem">The Binder abstraction</li><li class="listitem">Persistent publish-subscribe support</li><li class="listitem">Consumer group support</li><li class="listitem">Partitioning support</li><li class="listitem">A pluggable Binder API</li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_application_model" href="#_application_model"></a>24.1 Application Model</h2></div></div></div><p>A Spring Cloud Stream application consists of a middleware-neutral core.
|
|
The application communicates with the outside world through input and output <span class="emphasis"><em>channels</em></span> injected into it by Spring Cloud Stream.
|
|
Channels are connected to external brokers through middleware-specific Binder implementations.</p><div class="figure"><a name="d0e5821" href="#d0e5821"></a><p class="title"><b>Figure 24.1. Spring Cloud Stream Application</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/SCSt-with-binder.png" alt="SCSt with binder"></div></div></div><br class="figure-break"><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_fat_jar" href="#_fat_jar"></a>24.1.1 Fat JAR</h3></div></div></div><p>Spring Cloud Stream applications can be run in standalone mode from your IDE for testing.
|
|
To run a Spring Cloud Stream application in production, you can create an executable (or "fat") JAR by using the standard Spring Boot tooling provided for Maven or Gradle.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_the_binder_abstraction" href="#_the_binder_abstraction"></a>24.2 The Binder Abstraction</h2></div></div></div><p>Spring Cloud Stream provides Binder implementations for <a class="link" href="https://github.com/spring-cloud/spring-cloud-stream/tree/master/spring-cloud-stream-binders/spring-cloud-stream-binder-kafka" target="_top">Kafka</a> and <a class="link" href="https://github.com/spring-cloud/spring-cloud-stream/tree/master/spring-cloud-stream-binders/spring-cloud-stream-binder-rabbit" target="_top">Rabbit MQ</a>.
|
|
Spring Cloud Stream also includes a <a class="link" href="https://github.com/spring-cloud/spring-cloud-stream/blob/master/spring-cloud-stream-test-support/src/main/java/org/springframework/cloud/stream/test/binder/TestSupportBinder.java" target="_top">TestSupportBinder</a>, which leaves a channel unmodified so that tests can interact with channels directly and reliably assert on what is received.
|
|
You can use the extensible API to write your own Binder.</p><p>Spring Cloud Stream uses Spring Boot for configuration, and the Binder abstraction makes it possible for a Spring Cloud Stream application to be flexible in how it connects to middleware.
|
|
For example, deployers can dynamically choose, at runtime, the destinations (e.g., the Kafka topics or RabbitMQ exchanges) to which channels connect.
|
|
Such configuration can be provided through external configuration properties and in any form supported by Spring Boot (including application arguments, environment variables, and <code class="literal">application.yml</code> or <code class="literal">application.properties</code> files).
|
|
In the sink example from the <a class="xref" href="#_introducing_spring_cloud_stream" title="23. Introducing Spring Cloud Stream">Chapter 23, <i>Introducing Spring Cloud Stream</i></a> section, setting the application property <code class="literal">spring.cloud.stream.bindings.input.destination</code> to <code class="literal">raw-sensor-data</code> will cause it to read from the <code class="literal">raw-sensor-data</code> Kafka topic, or from a queue bound to the <code class="literal">raw-sensor-data</code> RabbitMQ exchange.</p><p>Spring Cloud Stream automatically detects and uses a binder found on the classpath.
|
|
You can easily use different types of middleware with the same code: just include a different binder at build time.
|
|
For more complex use cases, you can also package multiple binders with your application and have it choose the binder, and even whether to use different binders for different channels, at runtime.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_persistent_publish_subscribe_support" href="#_persistent_publish_subscribe_support"></a>24.3 Persistent Publish-Subscribe Support</h2></div></div></div><p>Communication between applications follows a publish-subscribe model, where data is broadcast through shared topics.
|
|
This can be seen in the following figure, which shows a typical deployment for a set of interacting Spring Cloud Stream applications.</p><div class="figure"><a name="d0e5878" href="#d0e5878"></a><p class="title"><b>Figure 24.2. Spring Cloud Stream Publish-Subscribe</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/SCSt-sensors.png" alt="SCSt sensors"></div></div></div><br class="figure-break"><p>Data reported by sensors to an HTTP endpoint is sent to a common destination named <code class="literal">raw-sensor-data</code>.
|
|
From the destination, it is independently processed by a microservice application that computes time-windowed averages and by another microservice application that ingests the raw data into HDFS.
|
|
In order to process the data, both applications declare the topic as their input at runtime.</p><p>The publish-subscribe communication model reduces the complexity of both the producer and the consumer, and allows new applications to be added to the topology without disruption of the existing flow.
|
|
For example, downstream from the average-calculating application, you can add an application that calculates the highest temperature values for display and monitoring.
|
|
You can then add another application that interprets the same flow of averages for fault detection.
|
|
Doing all communication through shared topics rather than point-to-point queues reduces coupling between microservices.</p><p>While the concept of publish-subscribe messaging is not new, Spring Cloud Stream takes the extra step of making it an opinionated choice for its application model.
|
|
By using native middleware support, Spring Cloud Stream also simplifies use of the publish-subscribe model across different platforms.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="consumer-groups" href="#consumer-groups"></a>24.4 Consumer Groups</h2></div></div></div><p>While the publish-subscribe model makes it easy to connect applications through shared topics, the ability to scale up by creating multiple instances of a given application is equally important.
|
|
When doing this, different instances of an application are placed in a competing consumer relationship, where only one of the instances is expected to handle a given message.</p><p>Spring Cloud Stream models this behavior through the concept of a <span class="emphasis"><em>consumer group</em></span>.
|
|
(Spring Cloud Stream consumer groups are similar to and inspired by Kafka consumer groups.)
|
|
Each consumer binding can use the <code class="literal">spring.cloud.stream.bindings.<channelName>.group</code> property to specify a group name.
|
|
For the consumers shown in the following figure, this property would be set as <code class="literal">spring.cloud.stream.bindings.<channelName>.group=hdfsWrite</code> or <code class="literal">spring.cloud.stream.bindings.<channelName>.group=average</code>.</p><div class="figure"><a name="d0e5915" href="#d0e5915"></a><p class="title"><b>Figure 24.3. Spring Cloud Stream Consumer Groups</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/SCSt-groups.png" alt="SCSt groups"></div></div></div><br class="figure-break"><p>All groups which subscribe to a given destination receive a copy of published data, but only one member of each group receives a given message from that destination.
|
|
By default, when a group is not specified, Spring Cloud Stream assigns the application to an anonymous and independent single-member consumer group that is in a publish-subscribe relationship with all other consumer groups.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="durability" href="#durability"></a>24.4.1 Durability</h3></div></div></div><p>Consistent with the opinionated application model of Spring Cloud Stream, consumer group subscriptions are <span class="emphasis"><em>durable</em></span>.
|
|
That is, a binder implementation ensures that group subscriptions are persistent, and once at least one subscription for a group has been created, the group will receive messages, even if they are sent while all applications in the group are stopped.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Anonymous subscriptions are non-durable by nature.
|
|
For some binder implementations (e.g., RabbitMQ), it is possible to have non-durable group subscriptions.</p></td></tr></table></div><p>In general, it is preferable to always specify a consumer group when binding an application to a given destination.
|
|
When scaling up a Spring Cloud Stream application, you must specify a consumer group for each of its input bindings.
|
|
This prevents the application’s instances from receiving duplicate messages (unless that behavior is desired, which is unusual).</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="partitioning" href="#partitioning"></a>24.5 Partitioning Support</h2></div></div></div><p>Spring Cloud Stream provides support for <span class="emphasis"><em>partitioning</em></span> data between multiple instances of a given application.
|
|
In a partitioned scenario, the physical communication medium (e.g., the broker topic) is viewed as being structured into multiple partitions.
|
|
One or more producer application instances send data to multiple consumer application instances and ensure that data identified by common characteristics are processed by the same consumer instance.</p><p>Spring Cloud Stream provides a common abstraction for implementing partitioned processing use cases in a uniform fashion.
|
|
Partitioning can thus be used whether the broker itself is naturally partitioned (e.g., Kafka) or not (e.g., RabbitMQ).</p><div class="figure"><a name="d0e5949" href="#d0e5949"></a><p class="title"><b>Figure 24.4. Spring Cloud Stream Partitioning</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/SCSt-partitioning.png" alt="SCSt partitioning"></div></div></div><br class="figure-break"><p>Partitioning is a critical concept in stateful processing, where it is critiical, for either performance or consistency reasons, to ensure that all related data is processed together.
|
|
For example, in the time-windowed average calculation example, it is important that all measurements from any given sensor are processed by the same application instance.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>To set up a partitioned processing scenario, you must configure both the data-producing and the data-consuming ends.</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_programming_model" href="#_programming_model"></a>25. Programming Model</h2></div></div></div><p>This section describes Spring Cloud Stream’s programming model.
|
|
Spring Cloud Stream provides a number of predefined annotations for declaring bound input and output channels as well as how to listen to channels.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_declaring_and_binding_channels" href="#_declaring_and_binding_channels"></a>25.1 Declaring and Binding Channels</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_triggering_binding_via_literal_enablebinding_literal" href="#_triggering_binding_via_literal_enablebinding_literal"></a>25.1.1 Triggering Binding Via <code class="literal">@EnableBinding</code></h3></div></div></div><p>You can turn a Spring application into a Spring Cloud Stream application by applying the <code class="literal">@EnableBinding</code> annotation to one of the application’s configuration classes.
|
|
The <code class="literal">@EnableBinding</code> annotation itself is meta-annotated with <code class="literal">@Configuration</code> and triggers the configuration of Spring Cloud Stream infrastructure:</p><pre class="programlisting">...
|
|
<em><span class="hl-annotation" style="color: gray">@Import(...)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableIntegration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <em><span class="hl-annotation" style="color: gray">@interface</span></em> EnableBinding {
|
|
...
|
|
Class<?>[] value() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">default</span> {};
|
|
}</pre><p>The <code class="literal">@EnableBinding</code> annotation can take as parameters one or more interface classes that contain methods which represent bindable components (typically message channels).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>In Spring Cloud Stream 1.0, the only supported bindable components are the Spring Messaging <code class="literal">MessageChannel</code> and its extensions <code class="literal">SubscribableChannel</code> and <code class="literal">PollableChannel</code>.
|
|
Future versions should extend this support to other types of components, using the same mechanism.
|
|
In this documentation, we will continue to refer to channels.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__literal_input_literal_and_literal_output_literal" href="#__literal_input_literal_and_literal_output_literal"></a>25.1.2 <code class="literal">@Input</code> and <code class="literal">@Output</code></h3></div></div></div><p>A Spring Cloud Stream application can have an arbitrary number of input and output channels defined in an interface as <code class="literal">@Input</code> and <code class="literal">@Output</code> methods:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Barista {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Input</span></em>
|
|
SubscribableChannel orders();
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Output</span></em>
|
|
MessageChannel hotDrinks();
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Output</span></em>
|
|
MessageChannel coldDrinks();
|
|
}</pre><p>Using this interface as a parameter to <code class="literal">@EnableBinding</code> will trigger the creation of three bound channels named <code class="literal">orders</code>, <code class="literal">hotDrinks</code>, and <code class="literal">coldDrinks</code>, respectively.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Barista.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CafeConfiguration {
|
|
|
|
...
|
|
}</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_customizing_channel_names" href="#_customizing_channel_names"></a>Customizing Channel Names</h4></div></div></div><p>Using the <code class="literal">@Input</code> and <code class="literal">@Output</code> annotations, you can specify a customized channel name for the channel, as shown in the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Barista {
|
|
...
|
|
<em><span class="hl-annotation" style="color: gray">@Input("inboundOrders")</span></em>
|
|
SubscribableChannel orders();
|
|
}</pre><p>In this example, the created bound channel will be named <code class="literal">inboundOrders</code>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_source_literal_literal_sink_literal_and_literal_processor_literal" href="#__literal_source_literal_literal_sink_literal_and_literal_processor_literal"></a><code class="literal">Source</code>, <code class="literal">Sink</code>, and <code class="literal">Processor</code></h4></div></div></div><p>For easy addressing of the most common use cases, which involve either an input channel, an output channel, or both, Spring Cloud Stream provides three predefined interfaces out of the box.</p><p><code class="literal">Source</code> can be used for an application which has a single outbound channel.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Source {
|
|
|
|
String OUTPUT = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"output"</span>;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Output(Source.OUTPUT)</span></em>
|
|
MessageChannel output();
|
|
|
|
}</pre><p><code class="literal">Sink</code> can be used for an application which has a single inbound channel.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Sink {
|
|
|
|
String INPUT = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"input"</span>;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Input(Sink.INPUT)</span></em>
|
|
SubscribableChannel input();
|
|
|
|
}</pre><p><code class="literal">Processor</code> can be used for an application which has both an inbound channel and an outbound channel.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Processor <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Source, Sink {
|
|
}</pre><p>Spring Cloud Stream provides no special handling for any of these interfaces; they are only provided out of the box.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_accessing_bound_channels" href="#_accessing_bound_channels"></a>25.1.3 Accessing Bound Channels</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_injecting_the_bound_interfaces" href="#_injecting_the_bound_interfaces"></a>Injecting the Bound Interfaces</h4></div></div></div><p>For each bound interface, Spring Cloud Stream will generate a bean that implements the interface.
|
|
Invoking a <code class="literal">@Input</code>-annotated or <code class="literal">@Output</code>-annotated method of one of these beans will return the relevant bound channel.</p><p>The bean in the following example sends a message on the output channel when its <code class="literal">hello</code> method is invoked.
|
|
It invokes <code class="literal">output()</code> on the injected <code class="literal">Source</code> bean to retrieve the target channel.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Component</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SendingBean {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> Source source;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> SendingBean(Source source) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.source = source;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sayHello(String name) {
|
|
source.output().send(MessageBuilder.withPayload(name).build());
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_injecting_channels_directly" href="#_injecting_channels_directly"></a>Injecting Channels Directly</h4></div></div></div><p>Bound channels can be also injected directly:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Component</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SendingBean {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> MessageChannel output;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> SendingBean(MessageChannel output) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.output = output;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sayHello(String name) {
|
|
output.send(MessageBuilder.withPayload(name).build());
|
|
}
|
|
}</pre><p>If the name of the channel is customized on the declaring annotation, that name should be used instead of the method name.
|
|
Given the following declaration:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> CustomSource {
|
|
...
|
|
<em><span class="hl-annotation" style="color: gray">@Output("customOutput")</span></em>
|
|
MessageChannel output();
|
|
}</pre><p>The channel will be injected as shown in the following example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Component</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SendingBean {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> MessageChannel output;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> SendingBean(<em><span class="hl-annotation" style="color: gray">@Qualifier("customOutput")</span></em> MessageChannel output) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.output = output;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sayHello(String name) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.output.send(MessageBuilder.withPayload(name).build());
|
|
}
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_producing_and_consuming_messages" href="#_producing_and_consuming_messages"></a>25.1.4 Producing and Consuming Messages</h3></div></div></div><p>You can write a Spring Cloud Stream application using either Spring Integration annotations or Spring Cloud Stream’s <code class="literal">@StreamListener</code> annotation.
|
|
The <code class="literal">@StreamListener</code> annotation is modeled after other Spring Messaging annotations (such as <code class="literal">@MessageMapping</code>, <code class="literal">@JmsListener</code>, <code class="literal">@RabbitListener</code>, etc.) but adds content type management and type coercion features.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_native_spring_integration_support" href="#_native_spring_integration_support"></a>Native Spring Integration Support</h4></div></div></div><p>Because Spring Cloud Stream is based on Spring Integration, Stream completely inherits Integration’s foundation and infrastructure as well as the component itself.
|
|
For example, you can attach the output channel of a <code class="literal">Source</code> to a <code class="literal">MessageSource</code>:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Source.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TimerSource {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Value("${format}")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> String format;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@InboundChannelAdapter(value = Source.OUTPUT, poller = @Poller(fixedDelay = "${fixedDelay}", maxMessagesPerPoll = "1"))</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MessageSource<String> timerMessageSource() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> () -> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> GenericMessage<>(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SimpleDateFormat(format).format(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Date()));
|
|
}
|
|
}</pre><p>Or you can use a processor’s channels in a transformer:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TransformProcessor {
|
|
<em><span class="hl-annotation" style="color: gray">@Transformer(inputChannel = Processor.INPUT, outputChannel = Processor.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Object transform(String message) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> message.toUpperCase();
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_spring_integration_error_channel_support" href="#_spring_integration_error_channel_support"></a>Spring Integration Error Channel Support</h4></div></div></div><p>Spring Cloud Stream supports publishing error messages received by the Spring Integration global
|
|
error channel. Error messages sent to the <code class="literal">errorChannel</code> can be published to a specific destination
|
|
at the broker by configuring a binding for the outbound target named <code class="literal">error</code>. For example, to
|
|
publish error messages to a broker destination named "myErrors", provide the following property:
|
|
<code class="literal">spring.cloud.stream.bindings.error.destination=myErrors</code></p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_using_streamlistener_for_automatic_content_type_handling" href="#_using_streamlistener_for_automatic_content_type_handling"></a>Using @StreamListener for Automatic Content Type Handling</h4></div></div></div><p>Complementary to its Spring Integration support, Spring Cloud Stream provides its own <code class="literal">@StreamListener</code> annotation, modeled after other Spring Messaging annotations (e.g. <code class="literal">@MessageMapping</code>, <code class="literal">@JmsListener</code>, <code class="literal">@RabbitListener</code>, etc.).
|
|
The <code class="literal">@StreamListener</code> annotation provides a simpler model for handling inbound messages, especially when dealing with use cases that involve content type management and type coercion.</p><p>Spring Cloud Stream provides an extensible <code class="literal">MessageConverter</code> mechanism for handling data conversion by bound channels and for, in this case, dispatching to methods annotated with <code class="literal">@StreamListener</code>.
|
|
The following is an example of an application which processes external <code class="literal">Vote</code> events:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> VoteHandler {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
VotingService votingService;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(Sink.INPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> handle(Vote vote) {
|
|
votingService.record(vote);
|
|
}
|
|
}</pre><p>The distinction between <code class="literal">@StreamListener</code> and a Spring Integration <code class="literal">@ServiceActivator</code> is seen when considering an inbound <code class="literal">Message</code> that has a <code class="literal">String</code> payload and a <code class="literal">contentType</code> header of <code class="literal">application/json</code>.
|
|
In the case of <code class="literal">@StreamListener</code>, the <code class="literal">MessageConverter</code> mechanism will use the <code class="literal">contentType</code> header to parse the <code class="literal">String</code> payload into a <code class="literal">Vote</code> object.</p><p>As with other Spring Messaging methods, method arguments can be annotated with <code class="literal">@Payload</code>, <code class="literal">@Headers</code> and <code class="literal">@Header</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>For methods which return data, you must use the <code class="literal">@SendTo</code> annotation to specify the output binding destination for data returned by the method:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TransformProcessor {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
VotingService votingService;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(Processor.INPUT)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SendTo(Processor.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> VoteResult handle(Vote vote) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> votingService.record(vote);
|
|
}
|
|
}</pre></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_using_streamlistener_for_dispatching_messages_to_multiple_methods" href="#_using_streamlistener_for_dispatching_messages_to_multiple_methods"></a>Using @StreamListener for dispatching messages to multiple methods</h4></div></div></div><p>Since version 1.2, Spring Cloud Stream supports dispatching messages to multiple <code class="literal">@StreamListener</code> methods registered on an input channel, based on a condition.</p><p>In order to be eligible to support conditional dispatching, a method must satisfy the follow conditions:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">it must not return a value</li><li class="listitem">it must be an individual message handling method (reactive API methods are not supported)</li></ul></div><p>The condition is specified via a SpEL expression in the <code class="literal">condition</code> attribute of the annotation and is evaluated for each message.
|
|
All the handlers that match the condition will be invoked in the same thread and no assumption must be made about the order in which the invocations take place.</p><p>An example of using <code class="literal">@StreamListener</code> with dispatching conditions can be seen below.
|
|
In this example, all the messages bearing a header <code class="literal">type</code> with the value <code class="literal">foo</code> will be dispatched to the <code class="literal">receiveFoo</code> method, and all the messages bearing a header <code class="literal">type</code> with the value <code class="literal">bar</code> will be dispatched to the <code class="literal">receiveBar</code> method.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TestPojoWithAnnotatedArguments {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(target = Sink.INPUT, condition = "headers['type']=='foo'")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> receiveFoo(<em><span class="hl-annotation" style="color: gray">@Payload</span></em> FooPojo fooPojo) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// handle the message</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(target = Sink.INPUT, condition = "headers['type']=='bar'")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> receiveBar(<em><span class="hl-annotation" style="color: gray">@Payload</span></em> BarPojo barPojo) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// handle the message</span>
|
|
}
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Dispatching via <code class="literal">@StreamListener</code> conditions is only supported for handlers of individual messages, and not for reactive programming support (described below).</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_reactive_programming_support" href="#_reactive_programming_support"></a>25.1.5 Reactive Programming Support</h3></div></div></div><p>Spring Cloud Stream also supports the use of reactive APIs where incoming and outgoing data is handled as continuous data flows.
|
|
Support for reactive APIs is available via the <code class="literal">spring-cloud-stream-reactive</code>, which needs to be added explicitly to your project.</p><p>The programming model with reactive APIs is declarative, where instead of specifying how each individual message should be handled, you can use operators that describe functional transformations from inbound to outbound data flows.</p><p>Spring Cloud Stream supports the following reactive APIs:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Reactor</li><li class="listitem">RxJava 1.x</li></ul></div><p>In the future, it is intended to support a more generic model based on Reactive Streams.</p><p>The reactive programming model is also using the <code class="literal">@StreamListener</code> annotation for setting up reactive handlers. The differences are that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">the <code class="literal">@StreamListener</code> annotation must not specify an input or output, as they are provided as arguments and return values from the method;</li><li class="listitem">the arguments of the method must be annotated with <code class="literal">@Input</code> and <code class="literal">@Output</code> indicating which input or output will the incoming and respectively outgoing data flows connect to;</li><li class="listitem">the return value of the method, if any, will be annotated with <code class="literal">@Output</code>, indicating the input where data shall be sent.</li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Reactive programming support requires Java 1.8.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>As of Spring Cloud Stream 1.1.1 and later (starting with release train Brooklyn.SR2), reactive programming support requires the use of Reactor 3.0.4.RELEASE and higher.
|
|
Earlier Reactor versions (including 3.0.1.RELEASE, 3.0.2.RELEASE and 3.0.3.RELEASE) are not supported.
|
|
<code class="literal">spring-cloud-stream-reactive</code> will transitively retrieve the proper version, but it is possible for the project structure to manage the version of the <code class="literal">io.projectreactor:reactor-core</code> to an earlier release, especially when using Maven.
|
|
This is the case for projects generated via Spring Initializr with Spring Boot 1.x, which will override the Reactor version to <code class="literal">2.0.8.RELEASE</code>.
|
|
In such cases you must ensure that the proper version of the artifact is released.
|
|
This can be simply achieved by adding a direct dependency on <code class="literal">io.projectreactor:reactor-core</code> with a version of <code class="literal">3.0.4.RELEASE</code> or later to your project.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The use of term <code class="literal">reactive</code> is currently referring to the reactive APIs being used and not to the execution model being reactive (i.e. the bound endpoints are still using a 'push' rather than 'pull' model). While some backpressure support is provided by the use of Reactor, we do intend on the long run to support entirely reactive pipelines by the use of native reactive clients for the connected middleware.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_reactor_based_handlers" href="#_reactor_based_handlers"></a>Reactor-based handlers</h4></div></div></div><p>A Reactor based handler can have the following argument types:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">For arguments annotated with <code class="literal">@Input</code>, it supports the Reactor type <code class="literal">Flux</code>.
|
|
The parameterization of the inbound Flux follows the same rules as in the case of individual message handling: it can be the entire <code class="literal">Message</code>, a POJO which can be the <code class="literal">Message</code> payload, or a POJO which is the result of a transformation based on the <code class="literal">Message</code> content-type header. Multiple inputs are provided;</li><li class="listitem">For arguments annotated with <code class="literal">Output</code>, it supports the type <code class="literal">FluxSender</code> which connects a <code class="literal">Flux</code> produced by the method with an output. Generally speaking, specifying outputs as arguments is only recommended when the method can have multiple outputs;</li></ul></div><p>A Reactor based handler supports a return type of <code class="literal">Flux</code>, case in which it must be annotated with <code class="literal">@Output</code>. We recommend using the return value of the method when a single output flux is available.</p><p>Here is an example of a simple Reactor-based Processor.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> UppercaseTransformer {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Output(Processor.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Flux<String> receive(<em><span class="hl-annotation" style="color: gray">@Input(Processor.INPUT)</span></em> Flux<String> input) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> input.map(s -> s.toUpperCase());
|
|
}
|
|
}</pre><p>The same processor using output arguments looks like this:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> UppercaseTransformer {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> receive(<em><span class="hl-annotation" style="color: gray">@Input(Processor.INPUT)</span></em> Flux<String> input,
|
|
<em><span class="hl-annotation" style="color: gray">@Output(Processor.OUTPUT)</span></em> FluxSender output) {
|
|
output.send(input.map(s -> s.toUpperCase()));
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_rxjava_1_x_support" href="#_rxjava_1_x_support"></a>RxJava 1.x support</h4></div></div></div><p>RxJava 1.x handlers follow the same rules as Reactor-based one, but will use <code class="literal">Observable</code> and <code class="literal">ObservableSender</code> arguments and return types.</p><p>So the first example above will become:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> UppercaseTransformer {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Output(Processor.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Observable<String> receive(<em><span class="hl-annotation" style="color: gray">@Input(Processor.INPUT)</span></em> Observable<String> input) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> input.map(s -> s.toUpperCase());
|
|
}
|
|
}</pre><p>The second example above will become:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> UppercaseTransformer {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> receive(<em><span class="hl-annotation" style="color: gray">@Input(Processor.INPUT)</span></em> Observable<String> input,
|
|
<em><span class="hl-annotation" style="color: gray">@Output(Processor.OUTPUT)</span></em> ObservableSender output) {
|
|
output.send(input.map(s -> s.toUpperCase()));
|
|
}
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_aggregation" href="#_aggregation"></a>25.1.6 Aggregation</h3></div></div></div><p>Spring Cloud Stream provides support for aggregating multiple applications together, connecting their input and output channels directly and avoiding the additional cost of exchanging messages via a broker.
|
|
As of version 1.0 of Spring Cloud Stream, aggregation is supported only for the following types of applications:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="emphasis"><em>sources</em></span> - applications with a single output channel named <code class="literal">output</code>, typically having a single binding of the type <code class="literal">org.springframework.cloud.stream.messaging.Source</code></li><li class="listitem"><span class="emphasis"><em>sinks</em></span> - applications with a single input channel named <code class="literal">input</code>, typically having a single binding of the type <code class="literal">org.springframework.cloud.stream.messaging.Sink</code></li><li class="listitem"><span class="emphasis"><em>processors</em></span> - applications with a single input channel named <code class="literal">input</code> and a single output channel named <code class="literal">output</code>, typically having a single binding of the type <code class="literal">org.springframework.cloud.stream.messaging.Processor</code>.</li></ul></div><p>They can be aggregated together by creating a sequence of interconnected applications, in which the output channel of an element in the sequence is connected to the input channel of the next element, if it exists.
|
|
A sequence can start with either a <span class="emphasis"><em>source</em></span> or a <span class="emphasis"><em>processor</em></span>, it can contain an arbitrary number of <span class="emphasis"><em>processors</em></span> and must end with either a <span class="emphasis"><em>processor</em></span> or a <span class="emphasis"><em>sink</em></span>.</p><p>Depending on the nature of the starting and ending element, the sequence may have one or more bindable channels, as follows:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">if the sequence starts with a source and ends with a sink, all communication between the applications is direct and no channels will be bound</li><li class="listitem">if the sequence starts with a processor, then its input channel will become the <code class="literal">input</code> channel of the aggregate and will be bound accordingly</li><li class="listitem">if the sequence ends with a processor, then its output channel will become the <code class="literal">output</code> channel of the aggregate and will be bound accordingly</li></ul></div><p>Aggregation is performed using the <code class="literal">AggregateApplicationBuilder</code> utility class, as in the following example.
|
|
Let’s consider a project in which we have source, processor and a sink, which may be defined in the project, or may be contained in one of the project’s dependencies.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Each component (source, sink or processor) in an aggregate application must be provided in a separate package if the configuration classes use <code class="literal">@SpringBootApplication</code>.
|
|
This is required to avoid cross-talk between applications, due to the classpath scanning performed by <code class="literal">@SpringBootApplication</code> on the configuration classes inside the same package.
|
|
In the example below, it can be seen that the Source, Processor and Sink application classes are grouped in separate packages.
|
|
A possible alternative is to provide the source, sink or processor configuration in a separate <code class="literal">@Configuration</code> class, avoid the use of <code class="literal">@SpringBootApplication</code>/<code class="literal">@ComponentScan</code> and use those for aggregation.</p></td></tr></table></div><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.app.mysink;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SinkApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> Logger logger = LoggerFactory.getLogger(SinkApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@ServiceActivator(inputChannel=Sink.INPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> loggerSink(Object payload) {
|
|
logger.info(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Received: "</span> + payload);
|
|
}
|
|
}</pre><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.app.myprocessor;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ProcessorApplication {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Transformer</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String loggerSink(String payload) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> payload.toUpperCase();
|
|
}
|
|
}</pre><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.app.mysource;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Source.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SourceApplication {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@InboundChannelAdapter(value = Source.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String timerMessageSource() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SimpleDateFormat().format(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Date());
|
|
}
|
|
}</pre><p>Each configuration can be used for running a separate component, but in this case they can be aggregated together as follows:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.app;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SampleAggregateApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AggregateApplicationBuilder()
|
|
.from(SourceApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).args(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"--fixedDelay=5000"</span>)
|
|
.via(ProcessorApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)
|
|
.to(SinkApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).args(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"--debug=true"</span>).run(args);
|
|
}
|
|
}</pre><p>The starting component of the sequence is provided as argument to the <code class="literal">from()</code> method.
|
|
The ending component of the sequence is provided as argument to the <code class="literal">to()</code> method.
|
|
Intermediate processors are provided as argument to the <code class="literal">via()</code> method.
|
|
Multiple processors of the same type can be chained together (e.g. for pipelining transformations with different configurations).
|
|
For each component, the builder can provide runtime arguments for Spring Boot configuration.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_configuring_aggregate_application" href="#_configuring_aggregate_application"></a>Configuring aggregate application</h4></div></div></div><p>Spring Cloud Stream supports passing properties for the individual applications inside the aggregate application using 'namespace' as prefix.</p><p>The namespace can be set for applications as follows:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SampleAggregateApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AggregateApplicationBuilder()
|
|
.from(SourceApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).namespace(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"source"</span>).args(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"--fixedDelay=5000"</span>)
|
|
.via(ProcessorApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).namespace(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"processor1"</span>)
|
|
.to(SinkApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).namespace(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"sink"</span>).args(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"--debug=true"</span>).run(args);
|
|
}
|
|
}</pre><p>Once the 'namespace' is set for the individual applications, the application properties with the <code class="literal">namespace</code> as prefix can be passed to the aggregate application using any supported property source (commandline, environment properties etc.,)</p><p>For instance, to override the default <code class="literal">fixedDelay</code> and <code class="literal">debug</code> properties of 'source' and 'sink' applications:</p><pre class="screen">java -jar target/MyAggregateApplication-0.0.1-SNAPSHOT.jar --source.fixedDelay=10000 --sink.debug=false</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_configuring_binding_service_properties_for_non_self_contained_aggregate_application" href="#_configuring_binding_service_properties_for_non_self_contained_aggregate_application"></a>Configuring binding service properties for non self contained aggregate application</h4></div></div></div><p>The non self-contained aggregate application is bound to external broker via either or both the inbound/outbound components (typically, message channels) of the aggregate application while the applications inside the aggregate application are directly bound.
|
|
For example: a source application’s output and a processor application’s input are directly bound while the processor’s output channel is bound to an external destination at the broker.
|
|
When passing the binding service properties for non-self contained aggregate application, it is required to pass the binding service properties to the aggregate application instead of setting them as 'args' to individual child application.
|
|
For instance,</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SampleAggregateApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AggregateApplicationBuilder()
|
|
.from(SourceApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).namespace(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"source"</span>).args(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"--fixedDelay=5000"</span>)
|
|
.via(ProcessorApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).namespace(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"processor1"</span>).args(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"--debug=true"</span>).run(args);
|
|
}
|
|
}</pre><p>The binding properties like <code class="literal">--spring.cloud.stream.bindings.output.destination=processor-output</code> need to be specified as one of the external configuration properties (cmdline arg etc.,).</p></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_binders" href="#_binders"></a>26. Binders</h2></div></div></div><p>Spring Cloud Stream provides a Binder abstraction for use in connecting to physical destinations at the external middleware.
|
|
This section provides information about the main concepts behind the Binder SPI, its main components, and implementation-specific details.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_producers_and_consumers" href="#_producers_and_consumers"></a>26.1 Producers and Consumers</h2></div></div></div><div class="figure"><a name="d0e6630" href="#d0e6630"></a><p class="title"><b>Figure 26.1. Producers and Consumers</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/producers-consumers.png" alt="producers consumers"></div></div></div><br class="figure-break"><p>A <span class="emphasis"><em>producer</em></span> is any component that sends messages to a channel.
|
|
The channel can be bound to an external message broker via a Binder implementation for that broker.
|
|
When invoking the <code class="literal">bindProducer()</code> method, the first parameter is the name of the destination within the broker, the second parameter is the local channel instance to which the producer will send messages, and the third parameter contains properties (such as a partition key expression) to be used within the adapter that is created for that channel.</p><p>A <span class="emphasis"><em>consumer</em></span> is any component that receives messages from a channel.
|
|
As with a producer, the consumer’s channel can be bound to an external message broker.
|
|
When invoking the <code class="literal">bindConsumer()</code> method, the first parameter is the destination name, and a second parameter provides the name of a logical group of consumers.
|
|
Each group that is represented by consumer bindings for a given destination receives a copy of each message that a producer sends to that destination (i.e., publish-subscribe semantics).
|
|
If there are multiple consumer instances bound using the same group name, then messages will be load-balanced across those consumer instances so that each message sent by a producer is consumed by only a single consumer instance within each group (i.e., queueing semantics).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_binder_spi" href="#_binder_spi"></a>26.2 Binder SPI</h2></div></div></div><p>The Binder SPI consists of a number of interfaces, out-of-the box utility classes and discovery strategies that provide a pluggable mechanism for connecting to external middleware.</p><p>The key point of the SPI is the <code class="literal">Binder</code> interface which is a strategy for connecting inputs and outputs to external middleware.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Binder<T, C <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ConsumerProperties, P <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ProducerProperties> {
|
|
Binding<T> bindConsumer(String name, String group, T inboundBindTarget, C consumerProperties);
|
|
|
|
Binding<T> bindProducer(String name, T outboundBindTarget, P producerProperties);
|
|
}</pre><p>The interface is parameterized, offering a number of extension points:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">input and output bind targets - as of version 1.0, only <code class="literal">MessageChannel</code> is supported, but this is intended to be used as an extension point in the future;</li><li class="listitem">extended consumer and producer properties - allowing specific Binder implementations to add supplemental properties which can be supported in a type-safe manner.</li></ul></div><p>A typical binder implementation consists of the following</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">a class that implements the <code class="literal">Binder</code> interface;</li><li class="listitem">a Spring <code class="literal">@Configuration</code> class that creates a bean of the type above along with the middleware connection infrastructure;</li><li class="listitem">a <code class="literal">META-INF/spring.binders</code> file found on the classpath containing one or more binder definitions, e.g.</li></ul></div><pre class="screen">kafka:\
|
|
org.springframework.cloud.stream.binder.kafka.config.KafkaBinderConfiguration</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_binder_detection" href="#_binder_detection"></a>26.3 Binder Detection</h2></div></div></div><p>Spring Cloud Stream relies on implementations of the Binder SPI to perform the task of connecting channels to message brokers.
|
|
Each Binder implementation typically connects to one type of messaging system.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_classpath_detection" href="#_classpath_detection"></a>26.3.1 Classpath Detection</h3></div></div></div><p>By default, Spring Cloud Stream relies on Spring Boot’s auto-configuration to configure the binding process.
|
|
If a single Binder implementation is found on the classpath, Spring Cloud Stream will use it automatically.
|
|
For example, a Spring Cloud Stream project that aims to bind only to RabbitMQ can simply add the following dependency:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-binder-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>For the specific maven coordinates of other binder dependencies, please refer to the documentation of that binder implementation.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="multiple-binders" href="#multiple-binders"></a>26.4 Multiple Binders on the Classpath</h2></div></div></div><p>When multiple binders are present on the classpath, the application must indicate which binder is to be used for each channel binding.
|
|
Each binder configuration contains a <code class="literal">META-INF/spring.binders</code>, which is a simple properties file:</p><pre class="screen">rabbit:\
|
|
org.springframework.cloud.stream.binder.rabbit.config.RabbitServiceAutoConfiguration</pre><p>Similar files exist for the other provided binder implementations (e.g., Kafka), and custom binder implementations are expected to provide them, as well.
|
|
The key represents an identifying name for the binder implementation, whereas the value is a comma-separated list of configuration classes that each contain one and only one bean definition of type <code class="literal">org.springframework.cloud.stream.binder.Binder</code>.</p><p>Binder selection can either be performed globally, using the <code class="literal">spring.cloud.stream.defaultBinder</code> property (e.g., <code class="literal">spring.cloud.stream.defaultBinder=rabbit</code>) or individually, by configuring the binder on each channel binding.
|
|
For instance, a processor application (that has channels with the names <code class="literal">input</code> and <code class="literal">output</code> for read/write respectively) which reads from Kafka and writes to RabbitMQ can specify the following configuration:</p><pre class="screen">spring.cloud.stream.bindings.input.binder=kafka
|
|
spring.cloud.stream.bindings.output.binder=rabbit</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="multiple-systems" href="#multiple-systems"></a>26.5 Connecting to Multiple Systems</h2></div></div></div><p>By default, binders share the application’s Spring Boot auto-configuration, so that one instance of each binder found on the classpath will be created.
|
|
If your application should connect to more than one broker of the same type, you can specify multiple binder configurations, each with different environment settings.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Turning on explicit binder configuration will disable the default binder configuration process altogether.
|
|
If you do this, all binders in use must be included in the configuration.
|
|
Frameworks that intend to use Spring Cloud Stream transparently may create binder configurations that can be referenced by name, but will not affect the default binder configuration.
|
|
In order to do so, a binder configuration may have its <code class="literal">defaultCandidate</code> flag set to false, e.g. <code class="literal">spring.cloud.stream.binders.<configurationName>.defaultCandidate=false</code>.
|
|
This denotes a configuration that will exist independently of the default binder configuration process.</p></td></tr></table></div><p>For example, this is the typical configuration for a processor application which connects to two RabbitMQ broker instances:</p><pre class="programlisting">spring:
|
|
cloud:
|
|
stream:
|
|
bindings:
|
|
input:
|
|
destination: foo
|
|
binder: rabbit1
|
|
output:
|
|
destination: bar
|
|
binder: rabbit2
|
|
binders:
|
|
rabbit1:
|
|
type: rabbit
|
|
environment:
|
|
spring:
|
|
rabbitmq:
|
|
host: <host1>
|
|
rabbit2:
|
|
type: rabbit
|
|
environment:
|
|
spring:
|
|
rabbitmq:
|
|
host: <host2></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_binder_configuration_properties" href="#_binder_configuration_properties"></a>26.6 Binder configuration properties</h2></div></div></div><p>The following properties are available when creating custom binder configurations.
|
|
They must be prefixed with <code class="literal">spring.cloud.stream.binders.<configurationName></code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">type</span></dt><dd><p class="simpara"> The binder type.
|
|
It typically references one of the binders found on the classpath, in particular a key in a <code class="literal">META-INF/spring.binders</code> file.</p><p class="simpara">By default, it has the same value as the configuration name.</p></dd><dt><span class="term">inheritEnvironment</span></dt><dd><p class="simpara">Whether the configuration will inherit the environment of the application itself.</p><p class="simpara">Default <code class="literal">true</code>.</p></dd><dt><span class="term">environment</span></dt><dd><p class="simpara"> Root for a set of properties that can be used to customize the environment of the binder.
|
|
When this is configured, the context in which the binder is being created is not a child of the application context.
|
|
This allows for complete separation between the binder components and the application components.</p><p class="simpara">Default <code class="literal">empty</code>.</p></dd><dt><span class="term">defaultCandidate</span></dt><dd><p class="simpara"> Whether the binder configuration is a candidate for being considered a default binder, or can be used only when explicitly referenced.
|
|
This allows adding binder configurations without interfering with the default processing.</p><p class="simpara">Default <code class="literal">true</code>.</p></dd></dl></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_configuration_options" href="#_configuration_options"></a>27. Configuration Options</h2></div></div></div><p>Spring Cloud Stream supports general configuration options as well as configuration for bindings and binders.
|
|
Some binders allow additional binding properties to support middleware-specific features.</p><p>Configuration options can be provided to Spring Cloud Stream applications via any mechanism supported by Spring Boot.
|
|
This includes application arguments, environment variables, and YAML or .properties files.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_cloud_stream_properties" href="#_spring_cloud_stream_properties"></a>27.1 Spring Cloud Stream Properties</h2></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.instanceCount</span></dt><dd><p class="simpara"> The number of deployed instances of an application.
|
|
Must be set for partitioning and if using Kafka.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">spring.cloud.stream.instanceIndex</span></dt><dd> The instance index of the application: a number from <code class="literal">0</code> to <code class="literal">instanceCount</code>-1.
|
|
Used for partitioning and with Kafka.
|
|
Automatically set in Cloud Foundry to match the application’s instance index.</dd><dt><span class="term">spring.cloud.stream.dynamicDestinations</span></dt><dd><p class="simpara"> A list of destinations that can be bound dynamically (for example, in a dynamic routing scenario).
|
|
If set, only listed destinations can be bound.</p><p class="simpara">Default: empty (allowing any destination to be bound).</p></dd><dt><span class="term">spring.cloud.stream.defaultBinder</span></dt><dd><p class="simpara"> The default binder to use, if multiple binders are configured.
|
|
See <a class="link" href="#multiple-binders" title="26.4 Multiple Binders on the Classpath">Multiple Binders on the Classpath</a>.</p><p class="simpara">Default: empty.</p></dd><dt><span class="term">spring.cloud.stream.overrideCloudConnectors</span></dt><dd><p class="simpara"> This property is only applicable when the <code class="literal">cloud</code> profile is active and Spring Cloud Connectors are provided with the application.
|
|
If the property is false (the default), the binder will detect a suitable bound service (e.g. a RabbitMQ service bound in Cloud Foundry for the RabbitMQ binder) and will use it for creating connections (usually via Spring Cloud Connectors).
|
|
When set to true, this property instructs binders to completely ignore the bound services and rely on Spring Boot properties (e.g. relying on the <code class="literal">spring.rabbitmq.*</code> properties provided in the environment for the RabbitMQ binder).
|
|
The typical usage of this property is to be nested in a customized environment <a class="link" href="#multiple-systems" title="26.5 Connecting to Multiple Systems">when connecting to multiple systems</a>.</p><p class="simpara">Default: false.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="binding-properties" href="#binding-properties"></a>27.2 Binding Properties</h2></div></div></div><p>Binding properties are supplied using the format <code class="literal">spring.cloud.stream.bindings.<channelName>.<property>=<value></code>.
|
|
The <code class="literal"><channelName></code> represents the name of the channel being configured (e.g., <code class="literal">output</code> for a <code class="literal">Source</code>).</p><p>To avoid repetition, Spring Cloud Stream supports setting values for all channels, in the format <code class="literal">spring.cloud.stream.default.<property>=<value></code>.</p><p>In what follows, we indicate where we have omitted the <code class="literal">spring.cloud.stream.bindings.<channelName>.</code> prefix and focus just on the property name, with the understanding that the prefix will be included at runtime.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_properties_for_use_of_spring_cloud_stream" href="#_properties_for_use_of_spring_cloud_stream"></a>27.2.1 Properties for Use of Spring Cloud Stream</h3></div></div></div><p>The following binding properties are available for both input and output bindings and must be prefixed with <code class="literal">spring.cloud.stream.bindings.<channelName>.</code>, e.g. <code class="literal">spring.cloud.stream.bindings.input.destination=ticktock</code>.</p><p>Default values can be set by using the prefix <code class="literal">spring.cloud.stream.default</code>, e.g. <code class="literal">spring.cloud.stream.default.contentType=application/json</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">destination</span></dt><dd>The target destination of a channel on the bound middleware (e.g., the RabbitMQ exchange or Kafka topic).
|
|
If the channel is bound as a consumer, it could be bound to multiple destinations and the destination names can be specified as comma separated String values.
|
|
If not set, the channel name is used instead.
|
|
The default value of this property cannot be overridden.</dd><dt><span class="term">group</span></dt><dd><p class="simpara"> The consumer group of the channel.
|
|
Applies only to inbound bindings.
|
|
See <a class="link" href="#consumer-groups" title="24.4 Consumer Groups">Consumer Groups</a>.</p><p class="simpara">Default: null (indicating an anonymous consumer).</p></dd><dt><span class="term">contentType</span></dt><dd><p class="simpara">The content type of the channel.</p><p class="simpara">Default: null (so that no type coercion is performed).</p></dd><dt><span class="term">binder</span></dt><dd><p class="simpara"> The binder used by this binding.
|
|
See <a class="xref" href="#multiple-binders" title="26.4 Multiple Binders on the Classpath">Section 26.4, “Multiple Binders on the Classpath”</a> for details.</p><p class="simpara">Default: null (the default binder will be used, if one exists).</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_consumer_properties" href="#_consumer_properties"></a>27.2.2 Consumer properties</h3></div></div></div><p>The following binding properties are available for input bindings only and must be prefixed with <code class="literal">spring.cloud.stream.bindings.<channelName>.consumer.</code>, e.g. <code class="literal">spring.cloud.stream.bindings.input.consumer.concurrency=3</code>.</p><p>Default values can be set by using the prefix <code class="literal">spring.cloud.stream.default.consumer</code>, e.g. <code class="literal">spring.cloud.stream.default.consumer.headerMode=raw</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">concurrency</span></dt><dd><p class="simpara">The concurrency of the inbound consumer.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">partitioned</span></dt><dd><p class="simpara">Whether the consumer receives data from a partitioned producer.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">headerMode</span></dt><dd><p class="simpara"> When set to <code class="literal">raw</code>, disables header parsing on input.
|
|
Effective only for messaging middleware that does not support message headers natively and requires header embedding.
|
|
Useful when inbound data is coming from outside Spring Cloud Stream applications.</p><p class="simpara">Default: <code class="literal">embeddedHeaders</code>.</p></dd><dt><span class="term">maxAttempts</span></dt><dd><p class="simpara">If processing fails, the number of attempts to process the message (including the first).
|
|
Set to 1 to disable retry.</p><p class="simpara">Default: <code class="literal">3</code>.</p></dd><dt><span class="term">backOffInitialInterval</span></dt><dd><p class="simpara">The backoff initial interval on retry.</p><p class="simpara">Default: <code class="literal">1000</code>.</p></dd><dt><span class="term">backOffMaxInterval</span></dt><dd><p class="simpara">The maximum backoff interval.</p><p class="simpara">Default: <code class="literal">10000</code>.</p></dd><dt><span class="term">backOffMultiplier</span></dt><dd><p class="simpara">The backoff multiplier.</p><p class="simpara">Default: <code class="literal">2.0</code>.</p></dd><dt><span class="term">instanceIndex</span></dt><dd><p class="simpara"> When set to a value greater than equal to zero, allows customizing the instance index of this consumer (if different from <code class="literal">spring.cloud.stream.instanceIndex</code>).
|
|
When set to a negative value, it will default to <code class="literal">spring.cloud.stream.instanceIndex</code>.</p><p class="simpara">Default: <code class="literal">-1</code>.</p></dd><dt><span class="term">instanceCount</span></dt><dd><p class="simpara"> When set to a value greater than equal to zero, allows customizing the instance count of this consumer (if different from <code class="literal">spring.cloud.stream.instanceCount</code>).
|
|
When set to a negative value, it will default to <code class="literal">spring.cloud.stream.instanceCount</code>.</p><p class="simpara">Default: <code class="literal">-1</code>.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_producer_properties" href="#_producer_properties"></a>27.2.3 Producer Properties</h3></div></div></div><p>The following binding properties are available for output bindings only and must be prefixed with <code class="literal">spring.cloud.stream.bindings.<channelName>.producer.</code>, e.g. <code class="literal">spring.cloud.stream.bindings.input.producer.partitionKeyExpression=payload.id</code>.</p><p>Default values can be set by using the prefix <code class="literal">spring.cloud.stream.default.producer</code>, e.g. <code class="literal">spring.cloud.stream.default.producer.partitionKeyExpression=payload.id</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">partitionKeyExpression</span></dt><dd><p class="simpara"> A SpEL expression that determines how to partition outbound data.
|
|
If set, or if <code class="literal">partitionKeyExtractorClass</code> is set, outbound data on this channel will be partitioned, and <code class="literal">partitionCount</code> must be set to a value greater than 1 to be effective.
|
|
The two options are mutually exclusive.
|
|
See <a class="xref" href="#partitioning" title="24.5 Partitioning Support">Section 24.5, “Partitioning Support”</a>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionKeyExtractorClass</span></dt><dd><p class="simpara"> A <code class="literal">PartitionKeyExtractorStrategy</code> implementation.
|
|
If set, or if <code class="literal">partitionKeyExpression</code> is set, outbound data on this channel will be partitioned, and <code class="literal">partitionCount</code> must be set to a value greater than 1 to be effective.
|
|
The two options are mutually exclusive.
|
|
See <a class="xref" href="#partitioning" title="24.5 Partitioning Support">Section 24.5, “Partitioning Support”</a>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionSelectorClass</span></dt><dd><p class="simpara"> A <code class="literal">PartitionSelectorStrategy</code> implementation.
|
|
Mutually exclusive with <code class="literal">partitionSelectorExpression</code>.
|
|
If neither is set, the partition will be selected as the <code class="literal">hashCode(key) % partitionCount</code>, where <code class="literal">key</code> is computed via either <code class="literal">partitionKeyExpression</code> or <code class="literal">partitionKeyExtractorClass</code>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionSelectorExpression</span></dt><dd><p class="simpara"> A SpEL expression for customizing partition selection.
|
|
Mutually exclusive with <code class="literal">partitionSelectorClass</code>.
|
|
If neither is set, the partition will be selected as the <code class="literal">hashCode(key) % partitionCount</code>, where <code class="literal">key</code> is computed via either <code class="literal">partitionKeyExpression</code> or <code class="literal">partitionKeyExtractorClass</code>.</p><p class="simpara">Default: null.</p></dd><dt><span class="term">partitionCount</span></dt><dd><p class="simpara"> The number of target partitions for the data, if partitioning is enabled.
|
|
Must be
|
|
set to a value greater than 1 if the producer is partitioned.
|
|
On Kafka, interpreted as a
|
|
hint; the larger of this and the partition count of the target topic is used instead.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">requiredGroups</span></dt><dd>A comma-separated list of groups to which the producer must ensure message delivery even if they start after it has been created (e.g., by pre-creating durable queues in RabbitMQ).</dd><dt><span class="term">headerMode</span></dt><dd><p class="simpara"> When set to <code class="literal">raw</code>, disables header embedding on output.
|
|
Effective only for messaging middleware that does not support message headers natively and requires header embedding.
|
|
Useful when producing data for non-Spring Cloud Stream applications.</p><p class="simpara">Default: <code class="literal">embeddedHeaders</code>.</p></dd><dt><span class="term">useNativeEncoding</span></dt><dd><p class="simpara"> When set to <code class="literal">true</code>, the outbound message is serialized directly by client library, which must be configured correspondingly (e.g. setting an appropriate Kafka producer value serializer).
|
|
When this configuration is being used, the outbound message marshalling is not based on the <code class="literal">contentType</code> of the binding.
|
|
When native encoding is used, it is the responsibility of the consumer to use appropriate decoder (ex: Kafka consumer value de-serializer) to deserialize the inbound message.
|
|
Also, when native encoding/decoding is used the <code class="literal">headerMode</code> property is ignored and headers will not be embedded into the message.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dynamicdestination" href="#dynamicdestination"></a>27.3 Using dynamically bound destinations</h2></div></div></div><p>Besides the channels defined via <code class="literal">@EnableBinding</code>, Spring Cloud Stream allows applications to send messages to dynamically bound destinations.
|
|
This is useful, for example, when the target destination needs to be determined at runtime.
|
|
Applications can do so by using the <code class="literal">BinderAwareChannelResolver</code> bean, registered automatically by the <code class="literal">@EnableBinding</code> annotation.</p><p>The property 'spring.cloud.stream.dynamicDestinations' can be used for restricting the dynamic destination names to a set known beforehand (whitelisting).
|
|
If the property is not set, any destination can be bound dynamicaly.</p><p>The <code class="literal">BinderAwareChannelResolver</code> can be used directly as in the following example, in which a REST controller uses a path variable to decide the target channel.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Controller</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SourceWithDynamicDestination {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> BinderAwareChannelResolver resolver;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(path = "/{target}", method = POST, consumes = "*/*")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ResponseStatus(HttpStatus.ACCEPTED)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> handleRequest(<em><span class="hl-annotation" style="color: gray">@RequestBody</span></em> String body, <em><span class="hl-annotation" style="color: gray">@PathVariable("target")</span></em> target,
|
|
<em><span class="hl-annotation" style="color: gray">@RequestHeader(HttpHeaders.CONTENT_TYPE)</span></em> Object contentType) {
|
|
sendMessage(body, target, contentType);
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sendMessage(String body, String target, Object contentType) {
|
|
resolver.resolveDestination(target).send(MessageBuilder.createMessage(body,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MessageHeaders(Collections.singletonMap(MessageHeaders.CONTENT_TYPE, contentType))));
|
|
}
|
|
}</pre><p>After starting the application on the default port 8080, when sending the following data:</p><pre class="screen">curl -H "Content-Type: application/json" -X POST -d "customer-1" http://localhost:8080/customers
|
|
|
|
curl -H "Content-Type: application/json" -X POST -d "order-1" http://localhost:8080/orders</pre><p>The destinations 'customers' and 'orders' are created in the broker (for example: exchange in case of Rabbit or topic in case of Kafka) with the names 'customers' and 'orders', and the data is published to the appropriate destinations.</p><p>The <code class="literal">BinderAwareChannelResolver</code> is a general purpose Spring Integration <code class="literal">DestinationResolver</code> and can be injected in other components.
|
|
For example, in a router using a SpEL expression based on the <code class="literal">target</code> field of an incoming JSON message.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Controller</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SourceWithDynamicDestination {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> BinderAwareChannelResolver resolver;
|
|
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping(path = "/", method = POST, consumes = "application/json")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ResponseStatus(HttpStatus.ACCEPTED)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> handleRequest(<em><span class="hl-annotation" style="color: gray">@RequestBody</span></em> String body, <em><span class="hl-annotation" style="color: gray">@RequestHeader(HttpHeaders.CONTENT_TYPE)</span></em> Object contentType) {
|
|
sendMessage(body, contentType);
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sendMessage(Object body, Object contentType) {
|
|
routerChannel().send(MessageBuilder.createMessage(body,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MessageHeaders(Collections.singletonMap(MessageHeaders.CONTENT_TYPE, contentType))));
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean(name = "routerChannel")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MessageChannel routerChannel() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> DirectChannel();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ServiceActivator(inputChannel = "routerChannel")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ExpressionEvaluatingRouter router() {
|
|
ExpressionEvaluatingRouter router =
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ExpressionEvaluatingRouter(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SpelExpressionParser().parseExpression(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"payload.target"</span>));
|
|
router.setDefaultOutputChannelName(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"default-output"</span>);
|
|
router.setChannelResolver(resolver);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> router;
|
|
}
|
|
}</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="contenttypemanagement" href="#contenttypemanagement"></a>28. Content Type and Transformation</h2></div></div></div><p>To allow you to propagate information about the content type of produced messages, Spring Cloud Stream attaches, by default, a <code class="literal">contentType</code> header to outbound messages.
|
|
For middleware that does not directly support headers, Spring Cloud Stream provides its own mechanism of automatically wrapping outbound messages in an envelope of its own.
|
|
For middleware that does support headers, Spring Cloud Stream applications may receive messages with a given content type from non-Spring Cloud Stream applications.</p><p>Spring Cloud Stream can handle messages based on this information in two ways:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Through its <code class="literal">contentType</code> settings on inbound and outbound channels</li><li class="listitem">Through its argument mapping performed for methods annotated with <code class="literal">@StreamListener</code></li></ul></div><p>Spring Cloud Stream allows you to declaratively configure type conversion for inputs and outputs using the <code class="literal">spring.cloud.stream.bindings.<channelName>.content-type</code> property of a binding.
|
|
Note that general type conversion may also be accomplished easily by using a transformer inside your application.
|
|
Currently, Spring Cloud Stream natively supports the following type conversions commonly used in streams:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>JSON</strong></span> to/from <span class="strong"><strong>POJO</strong></span></li><li class="listitem"><span class="strong"><strong>JSON</strong></span> to/from <a class="link" href="https://github.com/spring-projects/spring-tuple/blob/master/spring-tuple/src/main/java/org/springframework/tuple/Tuple.java" target="_top">org.springframework.tuple.Tuple</a></li><li class="listitem"><span class="strong"><strong>Object</strong></span> to/from <span class="strong"><strong>byte[]</strong></span> : Either the raw bytes serialized for remote transport, bytes emitted by an application, or converted to bytes using Java serialization(requires the object to be Serializable)</li><li class="listitem"><span class="strong"><strong>String</strong></span> to/from <span class="strong"><strong>byte[]</strong></span></li><li class="listitem"><span class="strong"><strong>Object</strong></span> to <span class="strong"><strong>plain text</strong></span> (invokes the object’s <span class="emphasis"><em>toString()</em></span> method)</li></ul></div><p>Where <span class="emphasis"><em>JSON</em></span> represents either a byte array or String payload containing JSON.
|
|
Currently, Objects may be converted from a JSON byte array or String.
|
|
Converting to JSON always produces a String.</p><p>If no <code class="literal">content-type</code> property is set on an outbound channel, Spring Cloud Stream will serialize the payload using a serializer based on the <a class="link" href="https://github.com/EsotericSoftware/kryo" target="_top">Kryo</a> serialization framework.
|
|
Deserializing messages at the destination requires the payload class to be present on the receiver’s classpath.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mime-types" href="#mime-types"></a>28.1 MIME types</h2></div></div></div><p><code class="literal">content-type</code> values are parsed as media types, e.g., <code class="literal">application/json</code> or <code class="literal">text/plain;charset=UTF-8</code>.
|
|
MIME types are especially useful for indicating how to convert to String or byte[] content.
|
|
Spring Cloud Stream also uses MIME type format to represent Java types, using the general type <code class="literal">application/x-java-object</code> with a <code class="literal">type</code> parameter.
|
|
For example, <code class="literal">application/x-java-object;type=java.util.Map</code> or <code class="literal">application/x-java-object;type=com.bar.Foo</code> can be set as the <code class="literal">content-type</code> property of an input binding.
|
|
In addition, Spring Cloud Stream provides custom MIME types, notably, <code class="literal">application/x-spring-tuple</code> to specify a Tuple.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mime-types-and-java-types" href="#mime-types-and-java-types"></a>28.2 MIME types and Java types</h2></div></div></div><p>The type conversions Spring Cloud Stream provides out of the box are summarized in the following table:
|
|
'Source Payload' means the payload before conversion and 'Target Payload' means the 'payload' after conversion.
|
|
The type conversion can occur either on the 'producer' side (output) or at the 'consumer' side (input).</p><div class="informaltable"><table style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"><col class="col_3"><col class="col_4"><col class="col_5"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Source Payload</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Target Payload</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">content-type</code> header (source message)</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><code class="literal">content-type</code> header (after conversion)</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Comments</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>POJO</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>JSON String</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>ignored</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/json</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Tuple</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>JSON String</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>ignored</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/json</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>JSON is tailored for Tuple</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>POJO</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>String (toString())</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>ignored</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>text/plain, java.lang.String</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>POJO</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>byte[] (java.io serialized)</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>ignored</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/x-java-serialized-object</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>JSON byte[] or String</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>POJO</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/json (or none)</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/x-java-object</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>byte[] or String</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Serializable</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/x-java-serialized-object</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/x-java-object</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>JSON byte[] or String</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Tuple</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/json (or none)</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application/x-spring-tuple</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>byte[]</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>String</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>any</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>text/plain, java.lang.String</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>will apply any Charset specified in the content-type header</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>String</p></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>byte[]</p></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>any</p></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>application/octet-stream</p></td><td style="" align="left" valign="top"><p>will apply any Charset specified in the content-type header</p></td></tr></tbody></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Conversion applies to payloads that require type conversion.
|
|
For example, if an application produces an XML string with outputType=application/json, the payload will not be converted from XML to JSON.
|
|
This is because the payload send to the outbound channel is already a String so no conversion will be applied at runtime.
|
|
It is also important to note that when using the default serialization mechanism, the payload class must be shared between the sending and receiving application, and compatible with the binary content.
|
|
This can create issues when application code changes independently in the two applications, as the binary format and code may become incompatible.</p></td></tr></table></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>While conversion is supported for both inbound and outbound channels, it is especially recommended to be used for the conversion of outbound messages.
|
|
For the conversion of inbound messages, especially when the target is a POJO, the <code class="literal">@StreamListener</code> support will perform the conversion automatically.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customizing_message_conversion" href="#_customizing_message_conversion"></a>28.3 Customizing message conversion</h2></div></div></div><p>Besides the conversions that it supports out of the box, Spring Cloud Stream also supports registering your own message conversion implementations.
|
|
This allows you to send and receive data in a variety of custom formats, including binary, and associate them with specific <code class="literal">contentTypes</code>.
|
|
Spring Cloud Stream registers all the beans of type <code class="literal">org.springframework.messaging.converter.MessageConverter</code> as custom message converters along with the out of the box message converters.</p><p>If your message converter needs to work with a specific <code class="literal">content-type</code> and target class (for both input and output), then the message converter needs to extend <code class="literal">org.springframework.messaging.converter.AbstractMessageConverter</code>.
|
|
For conversion when using <code class="literal">@StreamListener</code>, a message converter that implements <code class="literal">org.springframework.messaging.converter.MessageConverter</code> would suffice.</p><p>Here is an example of creating a message converter bean (with the content-type <code class="literal">application/bar</code>) inside a Spring Cloud Stream application:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SinkApplication {
|
|
|
|
...
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MessageConverter customMessageConverter() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MyCustomMessageConverter();
|
|
}</pre><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyCustomMessageConverter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> AbstractMessageConverter {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MyCustomMessageConverter() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">super</span>(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MimeType(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>));
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> supports(Class<?> clazz) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> (Bar.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> == clazz);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> Object convertFromInternal(Message<?> message, Class<?> targetClass, Object conversionHint) {
|
|
Object payload = message.getPayload();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> (payload <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">instanceof</span> Bar ? payload : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Bar((<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">byte</span>[]) payload));
|
|
}
|
|
}</pre><p>Spring Cloud Stream also provides support for Avro-based converters and schema evolution.
|
|
See <a class="link" href="#schema-evolution" title="29. Schema evolution support">the specific section</a> for details.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="__literal_streamlistener_literal_and_message_conversion" href="#__literal_streamlistener_literal_and_message_conversion"></a>28.4 <code class="literal">@StreamListener</code> and Message Conversion</h2></div></div></div><p>The <code class="literal">@StreamListener</code> annotation provides a convenient way for converting incoming messages without the need to specify the content type of an input channel.
|
|
During the dispatching process to methods annotated with <code class="literal">@StreamListener</code>, a conversion will be applied automatically if the argument requires it.</p><p>For example, let’s consider a message with the String content <code class="literal">{"greeting":"Hello, world"}</code> and a <code class="literal">content-type</code> header of <code class="literal">application/json</code> is received on the input channel.
|
|
Let us consider the following application that receives it:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> GreetingMessage {
|
|
|
|
String greeting;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String getGreeting() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> greeting;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> setGreeting(String greeting) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.greeting = greeting;
|
|
}
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> GreetingSink {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(Sink.INPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> receive(Greeting greeting) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// handle Greeting</span>
|
|
}
|
|
}</pre><p>The argument of the method will be populated automatically with the POJO containing the unmarshalled form of the JSON String.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="schema-evolution" href="#schema-evolution"></a>29. Schema evolution support</h2></div></div></div><p>Spring Cloud Stream provides support for schema-based message converters through its <code class="literal">spring-cloud-stream-schema</code> module.
|
|
Currently, the only serialization format supported out of the box for schema-based message converters is Apache Avro, with more formats to be added in future versions.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_apache_avro_message_converters" href="#_apache_avro_message_converters"></a>29.1 Apache Avro Message Converters</h2></div></div></div><p>The <code class="literal">spring-cloud-stream-schema</code> module contains two types of message converters that can be used for Apache Avro serialization:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">converters using the class information of the serialized/deserialized objects, or a schema with a location known at startup;</li><li class="listitem">converters using a schema registry - they locate the schemas at runtime, as well as dynamically registering new schemas as domain objects evolve.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_converters_with_schema_support" href="#_converters_with_schema_support"></a>29.2 Converters with schema support</h2></div></div></div><p>The <code class="literal">AvroSchemaMessageConverter</code> supports serializing and deserializing messages either using a predefined schema or by using the schema information available in the class (either reflectively, or contained in the <code class="literal">SpecificRecord</code>).
|
|
If the target type of the conversion is a <code class="literal">GenericRecord</code>, then a schema must be set.</p><p>For using it, you can simply add it to the application context, optionally specifying one ore more <code class="literal">MimeTypes</code> to associate it with.
|
|
The default <code class="literal">MimeType</code> is <code class="literal">application/avro</code>.</p><p>Here is an example of configuring it in a sink application registering the Apache Avro <code class="literal">MessageConverter</code>, without a predefined schema:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SinkApplication {
|
|
|
|
...
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MessageConverter userMessageConverter() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AvroSchemaMessageConverter(MimeType.valueOf(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"avro/bytes"</span>));
|
|
}
|
|
}</pre><p>Conversely, here is an application that registers a converter with a predefined schema, to be found on the classpath:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SinkApplication {
|
|
|
|
...
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> MessageConverter userMessageConverter() {
|
|
AvroSchemaMessageConverter converter = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AvroSchemaMessageConverter(MimeType.valueOf(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"avro/bytes"</span>));
|
|
converter.setSchemaLocation(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ClassPathResource(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"schemas/User.avro"</span>));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> converter;
|
|
}
|
|
}</pre><p>In order to understand the schema registry client converter, we will describe the schema registry support first.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_schema_registry_support" href="#_schema_registry_support"></a>29.3 Schema Registry Support</h2></div></div></div><p>Most serialization models, especially the ones that aim for portability across different platforms and languages, rely on a schema that describes how the data is serialized in the binary payload.
|
|
In order to serialize the data and then to interpret it, both the sending and receiving sides must have access to a schema that describes the binary format.
|
|
In certain cases, the schema can be inferred from the payload type on serialization, or from the target type on deserialization, but in a lot of cases applications benefit from having access to an explicit schema that describes the binary data format.
|
|
A schema registry allows you to store schema information in a textual format (typically JSON) and makes that information accessible to various applications that need it to receive and send data in binary format.
|
|
A schema is referenceable as a tuple consisting of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">a <span class="emphasis"><em>subject</em></span> that is the logical name of the schema;</li><li class="listitem">the schema <span class="emphasis"><em>version</em></span>;</li><li class="listitem">the schema <span class="emphasis"><em>format</em></span> which describes the binary format of the data.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_schema_registry_server" href="#_schema_registry_server"></a>29.4 Schema Registry Server</h2></div></div></div><p>Spring Cloud Stream provides a schema registry server implementation.
|
|
In order to use it, you can simply add the <code class="literal">spring-cloud-stream-schema-server</code> artifact to your project and use the <code class="literal">@EnableSchemaRegistryServer</code> annotation, adding the schema registry server REST controller to your application.
|
|
This annotation is intended to be used with Spring Boot web applications, and the listening port of the server is controlled by the <code class="literal">server.port</code> setting.
|
|
The <code class="literal">spring.cloud.stream.schema.server.path</code> setting can be used to control the root path of the schema server (especially when it is embedded in other applications).
|
|
The <code class="literal">spring.cloud.stream.schema.server.allowSchemaDeletion</code> boolean setting enables the deletion of schema. By default this is disabled.</p><p>The schema registry server uses a relational database to store the schemas.
|
|
By default, it uses an embedded database.
|
|
You can customize the schema storage using the <a class="link" href="http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/#boot-features-sql" target="_top">Spring Boot SQL database and JDBC configuration options</a>.</p><p>A Spring Boot application enabling the schema registry looks as follows:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableSchemaRegistryServer</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> SchemaRegistryServerApplication {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(SchemaRegistryServerApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
}</pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_schema_registry_server_api" href="#_schema_registry_server_api"></a>29.4.1 Schema Registry Server API</h3></div></div></div><p>The Schema Registry Server API consists of the following operations:</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_post_literal" href="#__literal_post_literal"></a><code class="literal">POST /</code></h4></div></div></div><p>Register a new schema.</p><p>Accepts JSON payload with the following fields:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">subject</code> the schema subject;</li><li class="listitem"><code class="literal">format</code> the schema format;</li><li class="listitem"><code class="literal">definition</code> the schema definition.</li></ul></div><p>Response is a schema object in JSON format, with the following fields:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">id</code> the schema id;</li><li class="listitem"><code class="literal">subject</code> the schema subject;</li><li class="listitem"><code class="literal">format</code> the schema format;</li><li class="listitem"><code class="literal">version</code> the schema version;</li><li class="listitem"><code class="literal">definition</code> the schema definition.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_get_subject_format_version_literal" href="#__literal_get_subject_format_version_literal"></a><code class="literal">GET /{subject}/{format}/{version}</code></h4></div></div></div><p>Retrieve an existing schema by its subject, format and version.</p><p>Response is a schema object in JSON format, with the following fields:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">id</code> the schema id;</li><li class="listitem"><code class="literal">subject</code> the schema subject;</li><li class="listitem"><code class="literal">format</code> the schema format;</li><li class="listitem"><code class="literal">version</code> the schema version;</li><li class="listitem"><code class="literal">definition</code> the schema definition.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_get_subject_format_literal" href="#__literal_get_subject_format_literal"></a><code class="literal">GET /{subject}/{format}</code></h4></div></div></div><p>Retrieve a list of existing schema by its subject and format.</p><p>Response is a list of schemas with each schema object in JSON format, with the following fields:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">id</code> the schema id;</li><li class="listitem"><code class="literal">subject</code> the schema subject;</li><li class="listitem"><code class="literal">format</code> the schema format;</li><li class="listitem"><code class="literal">version</code> the schema version;</li><li class="listitem"><code class="literal">definition</code> the schema definition.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_get_schemas_id_literal" href="#__literal_get_schemas_id_literal"></a><code class="literal">GET /schemas/{id}</code></h4></div></div></div><p>Retrieve an existing schema by its id.</p><p>Response is a schema object in JSON format, with the following fields:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">id</code> the schema id;</li><li class="listitem"><code class="literal">subject</code> the schema subject;</li><li class="listitem"><code class="literal">format</code> the schema format;</li><li class="listitem"><code class="literal">version</code> the schema version;</li><li class="listitem"><code class="literal">definition</code> the schema definition.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_delete_subject_format_version_literal" href="#__literal_delete_subject_format_version_literal"></a><code class="literal">DELETE /{subject}/{format}/{version}</code></h4></div></div></div><p>Delete an existing schema by its subject, format and version.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_delete_schemas_id_literal" href="#__literal_delete_schemas_id_literal"></a><code class="literal">DELETE /schemas/{id}</code></h4></div></div></div><p>Delete an existing schema by its id.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="__literal_delete_subject_literal" href="#__literal_delete_subject_literal"></a><code class="literal">DELETE /{subject}</code></h4></div></div></div><p>Delete existing schemas by their subject.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>This note applies to users of Spring Cloud Stream 1.1.0.RELEASE only.
|
|
Spring Cloud Stream 1.1.0.RELEASE used the table name <code class="literal">schema</code> for storing <code class="literal">Schema</code> objects, which is a keyword in a number of database implementations.
|
|
To avoid any conflicts in the future, starting with 1.1.1.RELEASE we have opted for the name <code class="literal">SCHEMA_REPOSITORY</code> for the storage table.
|
|
Any Spring Cloud Stream 1.1.0.RELEASE users that are upgrading are advised to migrate their existing schemas to the new table before upgrading.</p></td></tr></table></div></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_schema_registry_client" href="#_schema_registry_client"></a>29.5 Schema Registry Client</h2></div></div></div><p>The client-side abstraction for interacting with schema registry servers is the <code class="literal">SchemaRegistryClient</code> interface, with the following structure:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> SchemaRegistryClient {
|
|
|
|
SchemaRegistrationResponse register(String subject, String format, String schema);
|
|
|
|
String fetch(SchemaReference schemaReference);
|
|
|
|
String fetch(Integer id);
|
|
|
|
}</pre><p>Spring Cloud Stream provides out of the box implementations for interacting with its own schema server, as well as for interacting with the Confluent Schema Registry.</p><p>A client for the Spring Cloud Stream schema registry can be configured using the <code class="literal">@EnableSchemaRegistryClient</code> as follows:</p><pre class="programlisting"> <em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableSchemaRegistryClient</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> AvroSinkApplication {
|
|
...
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The default converter is optimized to cache not only the schemas from the remote server but also the <code class="literal">parse()</code> and <code class="literal">toString()</code> methods that are quite expensive.
|
|
Because of this, it uses a <code class="literal">DefaultSchemaRegistryClient</code> that does not caches responses.
|
|
If you intend to use the client directly on your code, you can request a bean that also caches responses to be created.
|
|
To do that, just add the property <code class="literal">spring.cloud.stream.schemaRegistryClient.cached=true</code> to your application properties.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_schema_registry_client_properties" href="#_schema_registry_client_properties"></a>29.5.1 Schema Registry Client properties</h3></div></div></div><p>The Schema Registry Client supports the following properties:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.schemaRegistryClient.endpoint</span></dt><dd>The location of the schema-server.
|
|
Use a full URL when setting this, including protocol (<code class="literal">http</code> or <code class="literal">https</code>) , port and context path.</dd><dt><span class="term">Default</span></dt><dd><code class="literal"><a class="link" href="http://localhost:8990/" target="_top">http://localhost:8990/</a></code></dd><dt><span class="term">spring.cloud.stream.schemaRegistryClient.cached</span></dt><dd>Whether the client should cache schema server responses.
|
|
Normally set to <code class="literal">false</code>, as the caching happens in the message converter.
|
|
Clients using the schema registry client should set this to <code class="literal">true</code>.</dd><dt><span class="term">Default</span></dt><dd><code class="literal">true</code></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_avro_schema_registry_client_message_converters" href="#_avro_schema_registry_client_message_converters"></a>29.6 Avro Schema Registry Client Message Converters</h2></div></div></div><p>For Spring Boot applications that have a <code class="literal">SchemaRegistryClient</code> bean registered with the application context, Spring Cloud Stream will auto-configure an Apache Avro message converter that uses the schema registry client for schema management.
|
|
This eases schema evolution, as applications that receive messages can get easy access to a writer schema that can be reconciled with their own reader schema.</p><p>For outbound messages, the <code class="literal">MessageConverter</code> will be activated if the content type of the channel is set to <code class="literal">application/*+avro</code>, e.g.:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.stream.bindings.output.contentType</span>=application/*+avro</pre><p>During the outbound conversion, the message converter will try to infer the schemas of the outbound messages based on their type and register them to a subject based on the payload type using the <code class="literal">SchemaRegistryClient</code>.
|
|
If an identical schema is already found, then a reference to it will be retrieved.
|
|
If not, the schema will be registered and a new version number will be provided.
|
|
The message will be sent with a <code class="literal">contentType</code> header using the scheme <code class="literal">application/[prefix].[subject].v[version]+avro</code>, where <code class="literal">prefix</code> is configurable and <code class="literal">subject</code> is deduced from the payload type.</p><p>For example, a message of the type <code class="literal">User</code> may be sent as a binary payload with a content type of <code class="literal">application/vnd.user.v2+avro</code>, where <code class="literal">user</code> is the subject and <code class="literal">2</code> is the version number.</p><p>When receiving messages, the converter will infer the schema reference from the header of the incoming message and will try to retrieve it. The schema will be used as the writer schema in the deserialization process.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_avro_schema_registry_message_converter_properties" href="#_avro_schema_registry_message_converter_properties"></a>29.6.1 Avro Schema Registry Message Converter properties</h3></div></div></div><p>If you have enabled Avro based schema registry client by setting <code class="literal">spring.cloud.stream.bindings.output.contentType=application/*+avro</code> you can customize the behavior of the registration with the following properties.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.schema.avro.dynamicSchemaGenerationEnabled</span></dt><dd>Enable if you want the converter to use reflection to infer a Schema from a POJO.</dd><dt><span class="term">Default</span></dt><dd><code class="literal">false</code></dd><dt><span class="term">spring.cloud.stream.schema.avro.readerSchema</span></dt><dd>Avro compares schema versions by looking at a writer schema (origin payload) and a reader schema (your application payload), check <a class="link" href="https://avro.apache.org/docs/1.7.6/spec.html" target="_top">Avro</a> documentation for more information. If set, this overrides any lookups at the schema server and uses the local schema as the reader schema.</dd><dt><span class="term">Default</span></dt><dd><code class="literal">null</code></dd><dt><span class="term">spring.cloud.stream.schema.avro.schemaLocations</span></dt><dd>Register any <code class="literal">.avsc</code> files listed in this property with the Schema Server.</dd><dt><span class="term">Default</span></dt><dd><code class="literal">empty</code></dd><dt><span class="term">spring.cloud.stream.schema.avro.prefix</span></dt><dd>The prefix to be used on the Content-Type header.</dd><dt><span class="term">Default</span></dt><dd><code class="literal">vnd</code></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_schema_registration_and_resolution" href="#_schema_registration_and_resolution"></a>29.7 Schema Registration and Resolution</h2></div></div></div><p>To better understand how Spring Cloud Stream registers and resolves new schemas, as well as its use of Avro schema comparison features, we will provide two separate subsections below: one for the registration, and one for the resolution of schemas.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_schema_registration_process_serialization" href="#_schema_registration_process_serialization"></a>29.7.1 Schema Registration Process (Serialization)</h3></div></div></div><p>The first part of the registration process is extracting a schema from the payload that is being sent over a channel.
|
|
Avro types such as <code class="literal">SpecificRecord</code> or <code class="literal">GenericRecord</code> already contain a schema, which can be retrieved immediately from the instance.
|
|
In the case of POJOs a schema will be inferred if the property <code class="literal">spring.cloud.stream.schema.avro.dynamicSchemaGenerationEnabled</code> is set to <code class="literal">true</code> (the default).</p><div class="figure"><a name="d0e8172" href="#d0e8172"></a><p class="title"><b>Figure 29.1. Schema Writer Resolution Process</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/schema_resolution.png" align="middle" alt="schema resolution"></div></div></div><br class="figure-break"><p>Once a schema is obtained, the converter will then load its metadata (version) from the remote server.
|
|
First it queries a local cache, and if not found it then submits the data to the server that will reply with versioning information.
|
|
The converter will always cache the results to avoid the overhead of querying the Schema Server for every new message that needs to be serialized.</p><div class="figure"><a name="d0e8183" href="#d0e8183"></a><p class="title"><b>Figure 29.2. Schema Registration Process</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/registration.png" align="middle" alt="registration"></div></div></div><br class="figure-break"><p>With the schema version information, the converter sets the <code class="literal">contentType</code> header of the message to carry the version information such as <code class="literal">application/vnd.user.v1+avro</code></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_schema_resolution_process_deserialization" href="#_schema_resolution_process_deserialization"></a>29.7.2 Schema Resolution Process (Deserialization)</h3></div></div></div><p>When reading messages that contain version information (i.e. a <code class="literal">contentType</code> header with a scheme like above), the converter will query the Schema server to fetch the <span class="strong"><strong>writer</strong></span> schema of the message.
|
|
Once it has found the correct schema of the incoming message, it then retrieves the reader schema and using Avro’s schema resolution support reads it into the reader definition (setting defaults and missing properties).</p><div class="figure"><a name="d0e8210" href="#d0e8210"></a><p class="title"><b>Figure 29.3. Schema Reading Resolution Process</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/schema_reading.png" align="middle" alt="schema reading"></div></div></div><br class="figure-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>It’s important to understand the difference between a writer schema (the application that wrote the message) and a reader schema (the receiving application).
|
|
Please take a moment to read <a class="link" href="https://avro.apache.org/docs/1.7.6/spec.html" target="_top">the Avro terminology</a> and understand the process.
|
|
Spring Cloud Stream will always fetch the writer schema to determine how to read a message. If you want to get Avro’s schema evolution support working you need to make sure that a readerSchema was properly set for your application.</p></td></tr></table></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_inter_application_communication" href="#_inter_application_communication"></a>30. Inter-Application Communication</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_connecting_multiple_application_instances" href="#_connecting_multiple_application_instances"></a>30.1 Connecting Multiple Application Instances</h2></div></div></div><p>While Spring Cloud Stream makes it easy for individual Spring Boot applications to connect to messaging systems, the typical scenario for Spring Cloud Stream is the creation of multi-application pipelines, where microservice applications send data to each other.
|
|
You can achieve this scenario by correlating the input and output destinations of adjacent applications.</p><p>Supposing that a design calls for the Time Source application to send data to the Log Sink application, you can use a common destination named <code class="literal">ticktock</code> for bindings within both applications.</p><p>Time Source (that has the channel name <code class="literal">output</code>) will set the following property:</p><pre class="screen">spring.cloud.stream.bindings.output.destination=ticktock</pre><p>Log Sink (that has the channel name <code class="literal">input</code>) will set the following property:</p><pre class="screen">spring.cloud.stream.bindings.input.destination=ticktock</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_instance_index_and_instance_count" href="#_instance_index_and_instance_count"></a>30.2 Instance Index and Instance Count</h2></div></div></div><p>When scaling up Spring Cloud Stream applications, each instance can receive information about how many other instances of the same application exist and what its own instance index is.
|
|
Spring Cloud Stream does this through the <code class="literal">spring.cloud.stream.instanceCount</code> and <code class="literal">spring.cloud.stream.instanceIndex</code> properties.
|
|
For example, if there are three instances of a HDFS sink application, all three instances will have <code class="literal">spring.cloud.stream.instanceCount</code> set to <code class="literal">3</code>, and the individual applications will have <code class="literal">spring.cloud.stream.instanceIndex</code> set to <code class="literal">0</code>, <code class="literal">1</code>, and <code class="literal">2</code>, respectively.</p><p>When Spring Cloud Stream applications are deployed via Spring Cloud Data Flow, these properties are configured automatically; when Spring Cloud Stream applications are launched independently, these properties must be set correctly.
|
|
By default, <code class="literal">spring.cloud.stream.instanceCount</code> is <code class="literal">1</code>, and <code class="literal">spring.cloud.stream.instanceIndex</code> is <code class="literal">0</code>.</p><p>In a scaled-up scenario, correct configuration of these two properties is important for addressing partitioning behavior (see below) in general, and the two properties are always required by certain binders (e.g., the Kafka binder) in order to ensure that data are split correctly across multiple consumer instances.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_partitioning" href="#_partitioning"></a>30.3 Partitioning</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configuring_output_bindings_for_partitioning" href="#_configuring_output_bindings_for_partitioning"></a>30.3.1 Configuring Output Bindings for Partitioning</h3></div></div></div><p>An output binding is configured to send partitioned data by setting one and only one of its <code class="literal">partitionKeyExpression</code> or <code class="literal">partitionKeyExtractorClass</code> properties, as well as its <code class="literal">partitionCount</code> property.
|
|
For example, the following is a valid and typical configuration:</p><pre class="screen">spring.cloud.stream.bindings.output.producer.partitionKeyExpression=payload.id
|
|
spring.cloud.stream.bindings.output.producer.partitionCount=5</pre><p>Based on the above example configuration, data will be sent to the target partition using the following logic.</p><p>A partition key’s value is calculated for each message sent to a partitioned output channel based on the <code class="literal">partitionKeyExpression</code>.
|
|
The <code class="literal">partitionKeyExpression</code> is a SpEL expression which is evaluated against the outbound message for extracting the partitioning key.</p><p>If a SpEL expression is not sufficient for your needs, you can instead calculate the partition key value by setting the property <code class="literal">partitionKeyExtractorClass</code> to a class which implements the <code class="literal">org.springframework.cloud.stream.binder.PartitionKeyExtractorStrategy</code> interface.
|
|
While the SpEL expression should usually suffice, more complex cases may use the custom implementation strategy.
|
|
In that case, the property 'partitionKeyExtractorClass' can be set as follows:</p><pre class="screen">spring.cloud.stream.bindings.output.producer.partitionKeyExtractorClass=com.example.MyKeyExtractor
|
|
spring.cloud.stream.bindings.output.producer.partitionCount=5</pre><p>Once the message key is calculated, the partition selection process will determine the target partition as a value between <code class="literal">0</code> and <code class="literal">partitionCount - 1</code>.
|
|
The default calculation, applicable in most scenarios, is based on the formula <code class="literal">key.hashCode() % partitionCount</code>.
|
|
This can be customized on the binding, either by setting a SpEL expression to be evaluated against the 'key' (via the <code class="literal">partitionSelectorExpression</code> property) or by setting a <code class="literal">org.springframework.cloud.stream.binder.PartitionSelectorStrategy</code> implementation (via the <code class="literal">partitionSelectorClass</code> property).</p><p>The binding level properties for 'partitionSelectorExpression' and 'partitionSelectorClass' can be specified similar to the way 'partitionKeyExpression' and 'partitionKeyExtractorClass' properties are specified in the above examples.
|
|
Additional properties can be configured for more advanced scenarios, as described in the following section.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_spring_managed_custom_literal_partitionkeyextractorclass_literal_implementations" href="#_spring_managed_custom_literal_partitionkeyextractorclass_literal_implementations"></a>Spring-managed custom <code class="literal">PartitionKeyExtractorClass</code> implementations</h4></div></div></div><p>In the example above, a custom strategy such as <code class="literal">MyKeyExtractor</code> is instantiated by the Spring Cloud Stream directly.
|
|
In some cases, it is necessary for such a custom strategy implementation to be created as a Spring bean, for being able to be managed by Spring, so that it can perform dependency injection, property binding, etc.
|
|
This can be done by configuring it as a @Bean in the application context and using the fully qualified class name as the bean’s name, as in the following example.</p><pre class="screen">@Bean(name="com.example.MyKeyExtractor")
|
|
public MyKeyExtractor extractor() {
|
|
return new MyKeyExtractor();
|
|
}</pre><p>As a Spring bean, the custom strategy benefits from the full lifecycle of a Spring bean.
|
|
For example, if the implementation need access to the application context directly, it can make implement 'ApplicationContextAware'.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_configuring_input_bindings_for_partitioning" href="#_configuring_input_bindings_for_partitioning"></a>Configuring Input Bindings for Partitioning</h4></div></div></div><p>An input binding (with the channel name <code class="literal">input</code>) is configured to receive partitioned data by setting its <code class="literal">partitioned</code> property, as well as the <code class="literal">instanceIndex</code> and <code class="literal">instanceCount</code> properties on the application itself, as in the following example:</p><pre class="screen">spring.cloud.stream.bindings.input.consumer.partitioned=true
|
|
spring.cloud.stream.instanceIndex=3
|
|
spring.cloud.stream.instanceCount=5</pre><p>The <code class="literal">instanceCount</code> value represents the total number of application instances between which the data need to be partitioned, and the <code class="literal">instanceIndex</code> must be a unique value across the multiple instances, between <code class="literal">0</code> and <code class="literal">instanceCount - 1</code>.
|
|
The instance index helps each application instance to identify the unique partition (or, in the case of Kafka, the partition set) from which it receives data.
|
|
It is important to set both values correctly in order to ensure that all of the data is consumed and that the application instances receive mutually exclusive datasets.</p><p>While a scenario which using multiple instances for partitioned data processing may be complex to set up in a standalone case, Spring Cloud Dataflow can simplify the process significantly by populating both the input and output values correctly as well as relying on the runtime infrastructure to provide information about the instance index and instance count.</p></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_testing" href="#_testing"></a>31. Testing</h2></div></div></div><p>Spring Cloud Stream provides support for testing your microservice applications without connecting to a messaging system.
|
|
You can do that by using the <code class="literal">TestSupportBinder</code> provided by the <code class="literal">spring-cloud-stream-test-support</code> library, which can be added as a test dependency to the application:</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-test-support<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">TestSupportBinder</code> uses the Spring Boot autoconfiguration mechanism to supersede the other binders found on the classpath.
|
|
Therefore, when adding a binder as a dependency, make sure that the <code class="literal">test</code> scope is being used.</p></td></tr></table></div><p>The <code class="literal">TestSupportBinder</code> allows users to interact with the bound channels and inspect what messages are sent and received by the application</p><p>For outbound message channels, the <code class="literal">TestSupportBinder</code> registers a single subscriber and retains the messages emitted by the application in a <code class="literal">MessageCollector</code>.
|
|
They can be retrieved during tests and have assertions made against them.</p><p>The user can also send messages to inbound message channels, so that the consumer application can consume the messages.
|
|
The following example shows how to test both input and output channels on a processor.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(webEnvironment= SpringBootTest.WebEnvironment.RANDOM_PORT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ExampleTest {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> Processor processor;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> MessageCollector messageCollector;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SuppressWarnings("unchecked")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testWiring() {
|
|
Message<String> message = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> GenericMessage<>(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"hello"</span>);
|
|
processor.input().send(message);
|
|
Message<String> received = (Message<String>) messageCollector.forChannel(processor.output()).poll();
|
|
assertThat(received.getPayload(), equalTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"hello world"</span>));
|
|
}
|
|
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Processor.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MyProcessor {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> Processor channels;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Transformer(inputChannel = Processor.INPUT, outputChannel = Processor.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String transform(String in) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> in + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">" world"</span>;
|
|
}
|
|
}
|
|
}</pre><p>In the example above, we are creating an application that has an input and an output channel, bound through the <code class="literal">Processor</code> interface.
|
|
The bound interface is injected into the test so we can have access to both channels.
|
|
We are sending a message on the input channel and we are using the <code class="literal">MessageCollector</code> provided by Spring Cloud Stream’s test support to capture the message has been sent to the output channel as a result.
|
|
Once we have received the message, we can validate that the component functions correctly.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_health_indicator_4" href="#_health_indicator_4"></a>32. Health Indicator</h2></div></div></div><p>Spring Cloud Stream provides a health indicator for binders.
|
|
It is registered under the name of <code class="literal">binders</code> and can be enabled or disabled by setting the <code class="literal">management.health.binders.enabled</code> property.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_metrics_emitter" href="#_metrics_emitter"></a>33. Metrics Emitter</h2></div></div></div><p>Spring Cloud Stream provides a module called <code class="literal">spring-cloud-stream-metrics</code> that can be used to emit any available metric from <a class="link" href="https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-metrics.html" target="_top">Spring Boot metrics endpoint</a> to a named channel.
|
|
This module allow operators to collect metrics from stream applications without relying on polling their endpoints.</p><p>The module is activated when you set the destination name for metrics binding, e.g. <code class="literal">spring.cloud.stream.bindings.applicationMetrics.destination=<DESTINATION_NAME></code>.
|
|
<code class="literal">applicationMetrics</code> can be configured in a similar fashion to any other producer binding.
|
|
The default <code class="literal">contentType</code> setting of <code class="literal">applicationMetrics</code> is <code class="literal">application/json</code>.</p><p>The following properties can be used for customizing the emission of metrics:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.metrics.key</span></dt><dd>The name of the metric being emitted. Should be an unique value per application.</dd><dt><span class="term">Default</span></dt><dd><code class="literal">${spring.application.name:${vcap.application.name:${spring.config.name:application}}}</code></dd><dt><span class="term">spring.cloud.stream.metrics.prefix</span></dt><dd><p class="simpara">Prefix string to be prepended to the metrics key.</p><p class="simpara">Default: ``</p></dd><dt><span class="term">spring.cloud.stream.metrics.properties</span></dt><dd><p class="simpara">Just like the <code class="literal">includes</code> option, it allows white listing application properties that will be added to the metrics payload</p><p class="simpara">Default: null.</p></dd></dl></div><p>A detailed overview of the metrics export process can be found in the <a class="link" href="https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-metrics.html#production-ready-metric-writers" target="_top">Spring Boot reference documentation</a>.
|
|
Spring Cloud Stream provides a metric exporter named <code class="literal">application</code> that can be configured via regular <a class="link" href="https://github.com/spring-projects/spring-boot/blob/1.5.x/spring-boot-actuator/src/main/java/org/springframework/boot/actuate/metrics/export/TriggerProperties.java" target="_top">Spring Boot metrics configuration properties</a>.</p><p>The exporter can be configured either by using the global Spring Boot configuration settings for exporters, or by using exporter-specific properties.
|
|
For using the global configuration settings, the properties should be prefixed by <code class="literal">spring.metric.export</code> (e.g. <code class="literal">spring.metric.export.includes=integration**</code>).
|
|
These configuration options will apply to all exporters (unless they have been configured differently).
|
|
Alternatively, if it is intended to use configuration settings that are different from the other exporters (e.g. for restricting the number of metrics published), the Spring Cloud Stream provided metrics exporter can be configured using the prefix <code class="literal">spring.metrics.export.triggers.application</code> (e.g. <code class="literal">spring.metrics.export.triggers.application.includes=integration**</code>).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Due to Spring Boot’s <a class="link" href="https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html#boot-features-external-config-relaxed-binding" target="_top">relaxed binding</a> the value of a property being included can be slightly different than the original value.</p><p>As a rule of thumb, the metric exporter will attempt to normalize all the properties in a consistent format using the dot notation (e.g. <code class="literal">JAVA_HOME</code> becomes <code class="literal">java.home</code>).</p><p>The goal of normalization is to make downstream consumers of those metrics capable of receiving property names consistently, regardless of how they are set on the monitored application (<code class="literal">--spring.application.name</code> or <code class="literal">SPRING_APPLICATION_NAME</code> would always yield <code class="literal">spring.application.name</code>).</p></td></tr></table></div><p>Below is a sample of the data published to the channel in JSON format by the following command:</p><pre class="screen">java -jar time-source.jar \
|
|
--spring.cloud.stream.bindings.applicationMetrics.destination=someMetrics \
|
|
--spring.cloud.stream.metrics.properties=spring.application** \
|
|
--spring.metrics.export.includes=integration.channel.input**,integration.channel.output**</pre><p>The resulting JSON is:</p><pre class="programlisting">{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"time-source"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"metrics"</span>:[
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.errorRate.mean"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">0.0</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.errorRate.max"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">0.0</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.errorRate.min"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">0.0</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.errorRate.stdev"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">0.0</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.errorRate.count"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">0.0</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.sendCount"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">6.0</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.sendRate.mean"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">0.994885872292989</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.sendRate.max"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">1.006247080013156</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.sendRate.min"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">1.0012035220116378</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.sendRate.stdev"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">6.505181111084848E-4</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
},
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"integration.channel.output.sendRate.count"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"value"</span>:<span class="hl-number">6.0</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T16:56:35.790Z"</span>
|
|
}
|
|
],
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"createdTime"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-04-11T20:56:35.790Z"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"properties"</span>:{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spring.application.name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"time-source"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spring.application.index"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"0"</span>
|
|
}
|
|
}</pre></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_samples" href="#_samples"></a>34. Samples</h2></div></div></div><p>For Spring Cloud Stream samples, please refer to the <a class="link" href="https://github.com/spring-cloud/spring-cloud-stream-samples" target="_top">spring-cloud-stream-samples</a> repository on GitHub.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_getting_started" href="#_getting_started"></a>35. Getting Started</h2></div></div></div><p>To get started with creating Spring Cloud Stream applications, visit the <a class="link" href="https://start.spring.io" target="_top">Spring Initializr</a> and create a new Maven project named "GreetingSource".
|
|
Select Spring Boot {supported-spring-boot-version} in the dropdown.
|
|
In the <span class="emphasis"><em>Search for dependencies</em></span> text box type <code class="literal">Stream Rabbit</code> or <code class="literal">Stream Kafka</code> depending on what binder you want to use.</p><p>Next, create a new class, <code class="literal">GreetingSource</code>, in the same package as the <code class="literal">GreetingSourceApplication</code> class.
|
|
Give it the following code:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.stream.annotation.EnableBinding;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.stream.messaging.Source;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.integration.annotation.InboundChannelAdapter;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Source.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> GreetingSource {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@InboundChannelAdapter(Source.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String greet() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"hello world "</span> + System.currentTimeMillis();
|
|
}
|
|
}</pre><p>The <code class="literal">@EnableBinding</code> annotation is what triggers the creation of Spring Integration infrastructure components.
|
|
Specifically, it will create a Kafka connection factory, a Kafka outbound channel adapter, and the message channel defined inside the Source interface:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> Source {
|
|
|
|
String OUTPUT = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"output"</span>;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Output(Source.OUTPUT)</span></em>
|
|
MessageChannel output();
|
|
|
|
}</pre><p>The auto-configuration also creates a default poller, so that the <code class="literal">greet()</code> method will be invoked once per second.
|
|
The standard Spring Integration <code class="literal">@InboundChannelAdapter</code> annotation sends a message to the source’s output channel, using the return value as the payload of the message.</p><p>To test-drive this setup, run a Kafka message broker.
|
|
An easy way to do this is to use a Docker image:</p><pre class="screen"># On OS X
|
|
$ docker run -p 2181:2181 -p 9092:9092 --env ADVERTISED_HOST=`docker-machine ip \`docker-machine active\`` --env ADVERTISED_PORT=9092 spotify/kafka
|
|
|
|
# On Linux
|
|
$ docker run -p 2181:2181 -p 9092:9092 --env ADVERTISED_HOST=localhost --env ADVERTISED_PORT=9092 spotify/kafka</pre><p>Build the application:</p><pre class="screen">./mvnw clean package</pre><p>The consumer application is coded in a similar manner.
|
|
Go back to Initializr and create another project, named LoggingSink.
|
|
Then create a new class, <code class="literal">LoggingSink</code>, in the same package as the class <code class="literal">LoggingSinkApplication</code> and with the following code:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.stream.annotation.EnableBinding;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.stream.annotation.StreamListener;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.stream.messaging.Sink;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> LoggingSink {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(Sink.INPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> log(String message) {
|
|
System.out.println(message);
|
|
}
|
|
}</pre><p>Build the application:</p><pre class="screen">./mvnw clean package</pre><p>To connect the GreetingSource application to the LoggingSink application, each application must share the same destination name.
|
|
Starting up both applications as shown below, you will see the consumer application printing "hello world" and a timestamp to the console:</p><pre class="screen">cd GreetingSource
|
|
java -jar target/GreetingSource-0.0.1-SNAPSHOT.jar --spring.cloud.stream.bindings.output.destination=mydest
|
|
|
|
cd LoggingSink
|
|
java -jar target/LoggingSink-0.0.1-SNAPSHOT.jar --server.port=8090 --spring.cloud.stream.bindings.input.destination=mydest</pre><p>(The different server port prevents collisions of the HTTP port used to service the Spring Boot Actuator endpoints in the two applications.)</p><p>The output of the LoggingSink application will look something like the following:</p><pre class="screen">[ main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8090 (http)
|
|
[ main] com.example.LoggingSinkApplication : Started LoggingSinkApplication in 6.828 seconds (JVM running for 7.371)
|
|
hello world 1458595076731
|
|
hello world 1458595077732
|
|
hello world 1458595078733
|
|
hello world 1458595079734
|
|
hello world 1458595080735</pre></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_binder_implementations" href="#_binder_implementations"></a>Part V. Binder Implementations</h1></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_apache_kafka_binder" href="#_apache_kafka_binder"></a>36. Apache Kafka Binder</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_usage" href="#_usage"></a>36.1 Usage</h2></div></div></div><p>For using the Apache Kafka binder, you just need to add it to your Spring Cloud Stream application, using the following Maven coordinates:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-binder-kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>Alternatively, you can also use the Spring Cloud Stream Kafka Starter.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-stream-kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_apache_kafka_binder_overview" href="#_apache_kafka_binder_overview"></a>36.2 Apache Kafka Binder Overview</h2></div></div></div><p>A simplified diagram of how the Apache Kafka binder operates can be seen below.</p><div class="figure"><a name="d0e8691" href="#d0e8691"></a><p class="title"><b>Figure 36.1. Kafka Binder</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/kafka-binder.png" alt="kafka binder"></div></div></div><br class="figure-break"><p>The Apache Kafka Binder implementation maps each destination to an Apache Kafka topic.
|
|
The consumer group maps directly to the same Apache Kafka concept.
|
|
Partitioning also maps directly to Apache Kafka partitions as well.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_configuration_options_2" href="#_configuration_options_2"></a>36.3 Configuration Options</h2></div></div></div><p>This section contains the configuration options used by the Apache Kafka binder.</p><p>For common configuration options and properties pertaining to binder, refer to the <a class="link" href="#binding-properties" title="27.2 Binding Properties">core documentation</a>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_kafka_binder_properties" href="#_kafka_binder_properties"></a>36.3.1 Kafka Binder Properties</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.kafka.binder.brokers</span></dt><dd><p class="simpara">A list of brokers to which the Kafka binder will connect.</p><p class="simpara">Default: <code class="literal">localhost</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.defaultBrokerPort</span></dt><dd><p class="simpara"> <code class="literal">brokers</code> allows hosts specified with or without port information (e.g., <code class="literal">host1,host2:port2</code>).
|
|
This sets the default port when no port is configured in the broker list.</p><p class="simpara">Default: <code class="literal">9092</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.zkNodes</span></dt><dd><p class="simpara">A list of ZooKeeper nodes to which the Kafka binder can connect.</p><p class="simpara">Default: <code class="literal">localhost</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.defaultZkPort</span></dt><dd><p class="simpara"> <code class="literal">zkNodes</code> allows hosts specified with or without port information (e.g., <code class="literal">host1,host2:port2</code>).
|
|
This sets the default port when no port is configured in the node list.</p><p class="simpara">Default: <code class="literal">2181</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.configuration</span></dt><dd><p class="simpara"> Key/Value map of client properties (both producers and consumer) passed to all clients created by the binder.
|
|
Due to the fact that these properties will be used by both producers and consumers, usage should be restricted to common properties, especially security settings.</p><p class="simpara">Default: Empty map.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.headers</span></dt><dd><p class="simpara">The list of custom headers that will be transported by the binder.</p><p class="simpara">Default: empty.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.offsetUpdateTimeWindow</span></dt><dd><p class="simpara"> The frequency, in milliseconds, with which offsets are saved.
|
|
Ignored if <code class="literal">0</code>.</p><p class="simpara">Default: <code class="literal">10000</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.offsetUpdateCount</span></dt><dd><p class="simpara"> The frequency, in number of updates, which which consumed offsets are persisted.
|
|
Ignored if <code class="literal">0</code>.
|
|
Mutually exclusive with <code class="literal">offsetUpdateTimeWindow</code>.</p><p class="simpara">Default: <code class="literal">0</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.requiredAcks</span></dt><dd><p class="simpara">The number of required acks on the broker.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.minPartitionCount</span></dt><dd><p class="simpara"> Effective only if <code class="literal">autoCreateTopics</code> or <code class="literal">autoAddPartitions</code> is set.
|
|
The global minimum number of partitions that the binder will configure on topics on which it produces/consumes data.
|
|
It can be superseded by the <code class="literal">partitionCount</code> setting of the producer or by the value of <code class="literal">instanceCount</code> * <code class="literal">concurrency</code> settings of the producer (if either is larger).</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.replicationFactor</span></dt><dd><p class="simpara">The replication factor of auto-created topics if <code class="literal">autoCreateTopics</code> is active.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.autoCreateTopics</span></dt><dd><p class="simpara"> If set to <code class="literal">true</code>, the binder will create new topics automatically.
|
|
If set to <code class="literal">false</code>, the binder will rely on the topics being already configured.
|
|
In the latter case, if the topics do not exist, the binder will fail to start.
|
|
Of note, this setting is independent of the <code class="literal">auto.topic.create.enable</code> setting of the broker and it does not influence it: if the server is set to auto-create topics, they may be created as part of the metadata retrieval request, with default broker settings.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.autoAddPartitions</span></dt><dd><p class="simpara"> If set to <code class="literal">true</code>, the binder will create add new partitions if required.
|
|
If set to <code class="literal">false</code>, the binder will rely on the partition size of the topic being already configured.
|
|
If the partition count of the target topic is smaller than the expected value, the binder will fail to start.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.socketBufferSize</span></dt><dd><p class="simpara">Size (in bytes) of the socket buffer to be used by the Kafka consumers.</p><p class="simpara">Default: <code class="literal">2097152</code>.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_kafka_consumer_properties" href="#_kafka_consumer_properties"></a>36.3.2 Kafka Consumer Properties</h3></div></div></div><p>The following properties are available for Kafka consumers only and
|
|
must be prefixed with <code class="literal">spring.cloud.stream.kafka.bindings.<channelName>.consumer.</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">autoRebalanceEnabled</span></dt><dd><p class="simpara">When <code class="literal">true</code>, topic partitions will be automatically rebalanced between the members of a consumer group.
|
|
When <code class="literal">false</code>, each consumer will be assigned a fixed set of partitions based on <code class="literal">spring.cloud.stream.instanceCount</code> and <code class="literal">spring.cloud.stream.instanceIndex</code>.
|
|
This requires both <code class="literal">spring.cloud.stream.instanceCount</code> and <code class="literal">spring.cloud.stream.instanceIndex</code> properties to be set appropriately on each launched instance.
|
|
The property <code class="literal">spring.cloud.stream.instanceCount</code> must typically be greater than 1 in this case.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">autoCommitOffset</span></dt><dd><p class="simpara"> Whether to autocommit offsets when a message has been processed.
|
|
If set to <code class="literal">false</code>, a header with the key <code class="literal">kafka_acknowledgment</code> of the type <code class="literal">org.springframework.kafka.support.Acknowledgment</code> header will be present in the inbound message.
|
|
Applications may use this header for acknowledging messages.
|
|
See the examples section for details.
|
|
When this property is set to <code class="literal">false</code>, Kafka binder will set the ack mode to <code class="literal">org.springframework.kafka.listener.AbstractMessageListenerContainer.AckMode.MANUAL</code>.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">autoCommitOnError</span></dt><dd><p class="simpara"> Effective only if <code class="literal">autoCommitOffset</code> is set to <code class="literal">true</code>.
|
|
If set to <code class="literal">false</code> it suppresses auto-commits for messages that result in errors, and will commit only for successful messages, allows a stream to automatically replay from the last successfully processed message, in case of persistent failures.
|
|
If set to <code class="literal">true</code>, it will always auto-commit (if auto-commit is enabled).
|
|
If not set (default), it effectively has the same value as <code class="literal">enableDlq</code>, auto-committing erroneous messages if they are sent to a DLQ, and not committing them otherwise.</p><p class="simpara">Default: not set.</p></dd><dt><span class="term">recoveryInterval</span></dt><dd><p class="simpara">The interval between connection recovery attempts, in milliseconds.</p><p class="simpara">Default: <code class="literal">5000</code>.</p></dd><dt><span class="term">resetOffsets</span></dt><dd><p class="simpara">Whether to reset offsets on the consumer to the value provided by <code class="literal">startOffset</code>.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">startOffset</span></dt><dd><p class="simpara"> The starting offset for new groups, or when <code class="literal">resetOffsets</code> is <code class="literal">true</code>.
|
|
Allowed values: <code class="literal">earliest</code>, <code class="literal">latest</code>.
|
|
If the consumer group is set explicitly for the consumer 'binding' (via <code class="literal">spring.cloud.stream.bindings.<channelName>.group</code>), then 'startOffset' is set to <code class="literal">earliest</code>; otherwise it is set to <code class="literal">latest</code> for the <code class="literal">anonymous</code> consumer group.</p><p class="simpara">Default: null (equivalent to <code class="literal">earliest</code>).</p></dd><dt><span class="term">enableDlq</span></dt><dd><p class="simpara">When set to true, it will send enable DLQ behavior for the consumer.
|
|
By default, messages that result in errors will be forwarded to a topic named <code class="literal">error.<destination>.<group></code>.
|
|
The DLQ topic name can be configurable via the property <code class="literal">dlqName</code>.
|
|
This provides an alternative option to the more common Kafka replay scenario for the case when the number of errors is relatively small and replaying the entire original topic may be too cumbersome.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">configuration</span></dt><dd><p class="simpara">Map with a key/value pair containing generic Kafka consumer properties.</p><p class="simpara">Default: Empty map.</p></dd><dt><span class="term">dlqName</span></dt><dd><p class="simpara">The name of the DLQ topic to receive the error messages.</p><p class="simpara">Default: null (If not specified, messages that result in errors will be forwarded to a topic named <code class="literal">error.<destination>.<group></code>).</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_kafka_producer_properties" href="#_kafka_producer_properties"></a>36.3.3 Kafka Producer Properties</h3></div></div></div><p>The following properties are available for Kafka producers only and
|
|
must be prefixed with <code class="literal">spring.cloud.stream.kafka.bindings.<channelName>.producer.</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">bufferSize</span></dt><dd><p class="simpara">Upper limit, in bytes, of how much data the Kafka producer will attempt to batch before sending.</p><p class="simpara">Default: <code class="literal">16384</code>.</p></dd><dt><span class="term">sync</span></dt><dd><p class="simpara">Whether the producer is synchronous.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">batchTimeout</span></dt><dd><p class="simpara"> How long the producer will wait before sending in order to allow more messages to accumulate in the same batch.
|
|
(Normally the producer does not wait at all, and simply sends all the messages that accumulated while the previous send was in progress.) A non-zero value may increase throughput at the expense of latency.</p><p class="simpara">Default: <code class="literal">0</code>.</p></dd><dt><span class="term">messageKeyExpression</span></dt><dd><p class="simpara"> A SpEL expression evaluated against the outgoing message used to populate the key of the produced Kafka message.
|
|
For example <code class="literal">headers.key</code> or <code class="literal">payload.myKey</code>.</p><p class="simpara">Default: <code class="literal">none</code>.</p></dd><dt><span class="term">configuration</span></dt><dd><p class="simpara">Map with a key/value pair containing generic Kafka producer properties.</p><p class="simpara">Default: Empty map.</p></dd></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The Kafka binder will use the <code class="literal">partitionCount</code> setting of the producer as a hint to create a topic with the given partition count (in conjunction with the <code class="literal">minPartitionCount</code>, the maximum of the two being the value being used).
|
|
Exercise caution when configuring both <code class="literal">minPartitionCount</code> for a binder and <code class="literal">partitionCount</code> for an application, as the larger value will be used.
|
|
If a topic already exists with a smaller partition count and <code class="literal">autoAddPartitions</code> is disabled (the default), then the binder will fail to start.
|
|
If a topic already exists with a smaller partition count and <code class="literal">autoAddPartitions</code> is enabled, new partitions will be added.
|
|
If a topic already exists with a larger number of partitions than the maximum of (<code class="literal">minPartitionCount</code> and <code class="literal">partitionCount</code>), the existing partition count will be used.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_usage_examples" href="#_usage_examples"></a>36.3.4 Usage examples</h3></div></div></div><p>In this section, we illustrate the use of the above properties for specific scenarios.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_example_setting_literal_autocommitoffset_literal_false_and_relying_on_manual_acking" href="#_example_setting_literal_autocommitoffset_literal_false_and_relying_on_manual_acking"></a>Example: Setting <code class="literal">autoCommitOffset</code> false and relying on manual acking.</h4></div></div></div><p>This example illustrates how one may manually acknowledge offsets in a consumer application.</p><p>This example requires that <code class="literal">spring.cloud.stream.kafka.bindings.input.consumer.autoCommitOffset</code> is set to false.
|
|
Use the corresponding input channel name for your example.</p><pre class="screen">@SpringBootApplication
|
|
@EnableBinding(Sink.class)
|
|
public class ManuallyAcknowdledgingConsumer {
|
|
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(ManuallyAcknowdledgingConsumer.class, args);
|
|
}
|
|
|
|
@StreamListener(Sink.INPUT)
|
|
public void process(Message<?> message) {
|
|
Acknowledgment acknowledgment = message.getHeaders().get(KafkaHeaders.ACKNOWLEDGMENT, Acknowledgment.class);
|
|
if (acknowledgment != null) {
|
|
System.out.println("Acknowledgment provided");
|
|
acknowledgment.acknowledge();
|
|
}
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_example_security_configuration" href="#_example_security_configuration"></a>Example: security configuration</h4></div></div></div><p>Apache Kafka 0.9 supports secure connections between client and brokers.
|
|
To take advantage of this feature, follow the guidelines in the <a class="link" href="http://kafka.apache.org/090/documentation.html#security_configclients" target="_top">Apache Kafka Documentation</a> as well as the Kafka 0.9 <a class="link" href="http://docs.confluent.io/2.0.0/kafka/security.html" target="_top">security guidelines from the Confluent documentation</a>.
|
|
Use the <code class="literal">spring.cloud.stream.kafka.binder.configuration</code> option to set security properties for all clients created by the binder.</p><p>For example, for setting <code class="literal">security.protocol</code> to <code class="literal">SASL_SSL</code>, set:</p><pre class="screen">spring.cloud.stream.kafka.binder.configuration.security.protocol=SASL_SSL</pre><p>All the other security properties can be set in a similar manner.</p><p>When using Kerberos, follow the instructions in the <a class="link" href="http://kafka.apache.org/090/documentation.html#security_sasl_clientconfig" target="_top">reference documentation</a> for creating and referencing the JAAS configuration.</p><p>Spring Cloud Stream supports passing JAAS configuration information to the application using a JAAS configuration file and using Spring Boot properties.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="_using_jaas_configuration_files" href="#_using_jaas_configuration_files"></a>Using JAAS configuration files</h5></div></div></div><p>The JAAS, and (optionally) krb5 file locations can be set for Spring Cloud Stream applications by using system properties.
|
|
Here is an example of launching a Spring Cloud Stream application with SASL and Kerberos using a JAAS configuration file:</p><pre class="screen"> java -Djava.security.auth.login.config=/path.to/kafka_client_jaas.conf -jar log.jar \
|
|
--spring.cloud.stream.kafka.binder.brokers=secure.server:9092 \
|
|
--spring.cloud.stream.kafka.binder.zkNodes=secure.zookeeper:2181 \
|
|
--spring.cloud.stream.bindings.input.destination=stream.ticktock \
|
|
--spring.cloud.stream.kafka.binder.configuration.security.protocol=SASL_PLAINTEXT</pre></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="_using_spring_boot_properties" href="#_using_spring_boot_properties"></a>Using Spring Boot properties</h5></div></div></div><p>As an alternative to having a JAAS configuration file, Spring Cloud Stream provides a mechanism for setting up the JAAS configuration for Spring Cloud Stream applications using Spring Boot properties.</p><p>The following properties can be used for configuring the login context of the Kafka client.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.kafka.binder.jaas.loginModule</span></dt><dd><p class="simpara">The login module name. Not necessary to be set in normal cases.</p><p class="simpara">Default: <code class="literal">com.sun.security.auth.module.Krb5LoginModule</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.jaas.controlFlag</span></dt><dd><p class="simpara">The control flag of the login module.</p><p class="simpara">Default: <code class="literal">required</code>.</p></dd><dt><span class="term">spring.cloud.stream.kafka.binder.jaas.options</span></dt><dd><p class="simpara">Map with a key/value pair containing the login module options.</p><p class="simpara">Default: Empty map.</p></dd></dl></div><p>Here is an example of launching a Spring Cloud Stream application with SASL and Kerberos using Spring Boot configuration properties:</p><pre class="screen"> java --spring.cloud.stream.kafka.binder.brokers=secure.server:9092 \
|
|
--spring.cloud.stream.kafka.binder.zkNodes=secure.zookeeper:2181 \
|
|
--spring.cloud.stream.bindings.input.destination=stream.ticktock \
|
|
--spring.cloud.stream.kafka.binder.autoCreateTopics=false \
|
|
--spring.cloud.stream.kafka.binder.configuration.security.protocol=SASL_PLAINTEXT \
|
|
--spring.cloud.stream.kafka.binder.jaas.options.useKeyTab=true \
|
|
--spring.cloud.stream.kafka.binder.jaas.options.storeKey=true \
|
|
--spring.cloud.stream.kafka.binder.jaas.options.keyTab=/etc/security/keytabs/kafka_client.keytab \
|
|
--spring.cloud.stream.kafka.binder.jaas.options.principal=kafka-client-1@EXAMPLE.COM</pre><p>This represents the equivalent of the following JAAS file:</p><pre class="screen">KafkaClient {
|
|
com.sun.security.auth.module.Krb5LoginModule required
|
|
useKeyTab=true
|
|
storeKey=true
|
|
keyTab="/etc/security/keytabs/kafka_client.keytab"
|
|
principal="kafka-client-1@EXAMPLE.COM";
|
|
};</pre><p>If the topics required already exist on the broker, or will be created by an administrator, autocreation can be turned off and only client JAAS properties need to be sent. As an alternative to setting <code class="literal">spring.cloud.stream.kafka.binder.autoCreateTopics</code> you can simply remove the broker dependency from the application. See <a class="xref" href="#exclude-admin-utils" title="Excluding Kafka broker jar from the classpath of the binder based application">the section called “Excluding Kafka broker jar from the classpath of the binder based application”</a> for details.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Do not mix JAAS configuration files and Spring Boot properties in the same application.
|
|
If the <code class="literal">-Djava.security.auth.login.config</code> system property is already present, Spring Cloud Stream will ignore the Spring Boot properties.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Exercise caution when using the <code class="literal">autoCreateTopics</code> and <code class="literal">autoAddPartitions</code> if using Kerberos.
|
|
Usually applications may use principals that do not have administrative rights in Kafka and Zookeeper, and relying on Spring Cloud Stream to create/modify topics may fail.
|
|
In secure environments, we strongly recommend creating topics and managing ACLs administratively using Kafka tooling.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_using_the_binder_with_apache_kafka_0_10" href="#_using_the_binder_with_apache_kafka_0_10"></a>Using the binder with Apache Kafka 0.10</h4></div></div></div><p>The default Kafka support in Spring Cloud Stream Kafka binder is for Kafka version 0.10.1.1. The binder also supports connecting to other 0.10 based versions and 0.9 clients.
|
|
In order to do this, when you create the project that contains your application, include <code class="literal">spring-cloud-starter-stream-kafka</code> as you normally would do for the default binder.
|
|
Then add these dependencies at the top of the <code class="literal"><dependencies></code> section in the pom.xml file to override the dependencies.</p><p>Here is an example for downgrading your application to 0.10.0.1. Since it is still on the 0.10 line, the default <code class="literal">spring-kafka</code> and <code class="literal">spring-integration-kafka</code> versions can be retained.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.apache.kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>kafka_2.11<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>0.10.0.1<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.slf4j<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>slf4j-log4j12<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.apache.kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>kafka-clients<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>0.10.0.1<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>Here is another example of using 0.9.0.1 version.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>1.0.5.RELEASE<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.integration<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-integration-kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>2.0.1.RELEASE<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.apache.kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>kafka_2.11<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>0.9.0.1<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.slf4j<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>slf4j-log4j12<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.apache.kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>kafka-clients<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>0.9.0.1<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The versions above are provided only for the sake of the example.
|
|
For best results, we recommend using the most recent 0.10-compatible versions of the projects.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="exclude-admin-utils" href="#exclude-admin-utils"></a>Excluding Kafka broker jar from the classpath of the binder based application</h4></div></div></div><p>The Apache Kafka Binder uses the administrative utilities which are part of the Apache Kafka server library to create and reconfigure topics.
|
|
If the inclusion of the Apache Kafka server library and its dependencies is not necessary at runtime because the application will rely on the topics being configured administratively, the Kafka binder allows for Apache Kafka server dependency to be excluded from the application.</p><p>If you use non default versions for Kafka dependencies as advised above, all you have to do is not to include the kafka broker dependency.
|
|
If you use the default Kafka version, then ensure that you exclude the kafka broker jar from the <code class="literal">spring-cloud-starter-stream-kafka</code> dependency as following.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-stream-kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.apache.kafka<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>kafka_2.11<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>If you exclude the Apache Kafka server dependency and the topic is not present on the server, then the Apache Kafka broker will create the topic if auto topic creation is enabled on the server.
|
|
Please keep in mind that if you are relying on this, then the Kafka server will use the default number of partitions and replication factors.
|
|
On the other hand, if auto topic creation is disabled on the server, then care must be taken before running the application to create the topic with the desired number of partitions.</p><p>If you want to have full control over how partitions are allocated, then leave the default settings as they are, i.e. do not exclude the kafka broker jar and ensure that <code class="literal">spring.cloud.stream.kafka.binder.autoCreateTopics</code> is set to <code class="literal">true</code>, which is the default.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kafka-dlq-processing" href="#kafka-dlq-processing"></a>36.4 Dead-Letter Topic Processing</h2></div></div></div><p>Because it can’t be anticipated how users would want to dispose of dead-lettered messages, the framework does not provide any standard mechanism to handle them.
|
|
If the reason for the dead-lettering is transient, you may wish to route the messages back to the original topic.
|
|
However, if the problem is a permanent issue, that could cause an infinite loop.
|
|
The following <code class="literal">spring-boot</code> application is an example of how to route those messages back to the original topic, but moves them to a third "parking lot" topic after three attempts.
|
|
The application is simply another spring-cloud-stream application that reads from the dead-letter topic.
|
|
It terminates when no messages are received for 5 seconds.</p><p>The examples assume the original destination is <code class="literal">so8400out</code> and the consumer group is <code class="literal">so8400</code>.</p><p>There are several considerations.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Consider only running the rerouting when the main application is not running.
|
|
Otherwise, the retries for transient errors will be used up very quickly.</li><li class="listitem">Alternatively, use a two-stage approach - use this application to route to a third topic, and another to route from there back to the main topic.</li><li class="listitem">Since this technique uses a message header to keep track of retries, it won’t work with <code class="literal">headerMode=raw</code>.
|
|
In that case, consider adding some data to the payload (that can be ignored by the main application).</li><li class="listitem"><code class="literal">x-retries</code> has to be added to the <code class="literal">headers</code> property <code class="literal">spring.cloud.stream.kafka.binder.headers=x-retries</code> on both this, and the main application so that the header is transported between the applications.</li><li class="listitem">Since kafka is publish/subscribe, replayed messages will be sent to each consumer group, even those that successfully processed a message the first time around.</li></ul></div><p><b>application.properties. </b>
|
|
</p><pre class="screen">spring.cloud.stream.bindings.input.group=so8400replay
|
|
spring.cloud.stream.bindings.input.destination=error.so8400out.so8400
|
|
|
|
spring.cloud.stream.bindings.output.destination=so8400out
|
|
spring.cloud.stream.bindings.output.producer.partitioned=true
|
|
|
|
spring.cloud.stream.bindings.parkingLot.destination=so8400in.parkingLot
|
|
spring.cloud.stream.bindings.parkingLot.producer.partitioned=true
|
|
|
|
spring.cloud.stream.kafka.binder.configuration.auto.offset.reset=earliest
|
|
|
|
spring.cloud.stream.kafka.binder.headers=x-retries</pre><p>
|
|
</p><p><b>Application. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(TwoOutputProcessor.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ReRouteDlqKApplication <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> CommandLineRunner {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_RETRIES_HEADER = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-retries"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(ReRouteDlqKApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args).close();
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> AtomicInteger processed = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AtomicInteger();
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> MessageChannel parkingLot;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(Processor.INPUT)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SendTo(Processor.OUTPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Message<?> reRoute(Message<?> failed) {
|
|
processed.incrementAndGet();
|
|
Integer retries = failed.getHeaders().get(X_RETRIES_HEADER, Integer.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retries == null) {
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"First retry for "</span> + failed);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> MessageBuilder.fromMessage(failed)
|
|
.setHeader(X_RETRIES_HEADER, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Integer(<span class="hl-number">1</span>))
|
|
.setHeader(BinderHeaders.PARTITION_OVERRIDE,
|
|
failed.getHeaders().get(KafkaHeaders.RECEIVED_PARTITION_ID))
|
|
.build();
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">else</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retries.intValue() < <span class="hl-number">3</span>) {
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Another retry for "</span> + failed);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> MessageBuilder.fromMessage(failed)
|
|
.setHeader(X_RETRIES_HEADER, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Integer(retries.intValue() + <span class="hl-number">1</span>))
|
|
.setHeader(BinderHeaders.PARTITION_OVERRIDE,
|
|
failed.getHeaders().get(KafkaHeaders.RECEIVED_PARTITION_ID))
|
|
.build();
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">else</span> {
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Retries exhausted for "</span> + failed);
|
|
parkingLot.send(MessageBuilder.fromMessage(failed)
|
|
.setHeader(BinderHeaders.PARTITION_OVERRIDE,
|
|
failed.getHeaders().get(KafkaHeaders.RECEIVED_PARTITION_ID))
|
|
.build());
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> null;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> run(String... args) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">while</span> (true) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> count = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.processed.get();
|
|
Thread.sleep(<span class="hl-number">5000</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (count == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.processed.get()) {
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Idle, terminating"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span>;
|
|
}
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> TwoOutputProcessor <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Processor {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Output("parkingLot")</span></em>
|
|
MessageChannel parkingLot();
|
|
|
|
}
|
|
|
|
}</pre><p>
|
|
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_rabbitmq_binder" href="#_rabbitmq_binder"></a>37. RabbitMQ Binder</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_usage_2" href="#_usage_2"></a>37.1 Usage</h2></div></div></div><p>For using the RabbitMQ binder, you just need to add it to your Spring Cloud Stream application, using the following Maven coordinates:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-binder-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>Alternatively, you can also use the Spring Cloud Stream RabbitMQ Starter.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-stream-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_rabbitmq_binder_overview" href="#_rabbitmq_binder_overview"></a>37.2 RabbitMQ Binder Overview</h2></div></div></div><p>A simplified diagram of how the RabbitMQ binder operates can be seen below.</p><div class="figure"><a name="d0e9456" href="#d0e9456"></a><p class="title"><b>Figure 37.1. RabbitMQ Binder</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/rabbit-binder.png" alt="rabbit binder"></div></div></div><br class="figure-break"><p>The RabbitMQ Binder implementation maps each destination to a <code class="literal">TopicExchange</code>.
|
|
For each consumer group, a <code class="literal">Queue</code> will be bound to that <code class="literal">TopicExchange</code>.
|
|
Each consumer instance have a corresponding RabbitMQ <code class="literal">Consumer</code> instance for its group’s <code class="literal">Queue</code>.
|
|
For partitioned producers/consumers the queues are suffixed with the partition index and use the partition index as routing key.</p><p>Using the <code class="literal">autoBindDlq</code> option, you can optionally configure the binder to create and configure dead-letter queues (DLQs) (and a dead-letter exchange <code class="literal">DLX</code>).
|
|
The dead letter queue has the name of the destination, appended with <code class="literal">.dlq</code>.
|
|
If retry is enabled (<code class="literal">maxAttempts > 1</code>) failed messages will be delivered to the DLQ.
|
|
If retry is disabled (<code class="literal">maxAttempts = 1</code>), you should set <code class="literal">requeueRejected</code> to <code class="literal">false</code> (default) so that a failed message will be routed to the DLQ, instead of being requeued.
|
|
In addition, <code class="literal">republishToDlq</code> causes the binder to publish a failed message to the DLQ (instead of rejecting it); this enables additional information to be added to the message in headers, such as the stack trace in the <code class="literal">x-exception-stacktrace</code> header.
|
|
This option does not need retry enabled; you can republish a failed message after just one attempt.
|
|
Starting with <span class="emphasis"><em>version 1.2</em></span>, you can configure the delivery mode of republished messsages; see property <code class="literal">republishDeliveryMode</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Setting <code class="literal">requeueRejected</code> to <code class="literal">true</code> will cause the message to be requeued and redelivered continually, which is likely not what you want unless the failure issue is transient.
|
|
In general, it’s better to enable retry within the binder by setting <code class="literal">maxAttempts</code> to greater than one, or set <code class="literal">republishToDlq</code> to <code class="literal">true</code>.</p></td></tr></table></div><p>See <a class="xref" href="#rabbit-binder-properties" title="37.3.1 RabbitMQ Binder Properties">Section 37.3.1, “RabbitMQ Binder Properties”</a> for more information about these properties.</p><p>The framework does not provide any standard mechanism to consume dead-letter messages (or to re-route them back to the primary queue).
|
|
Some options are described in <a class="xref" href="#rabbit-dlq-processing" title="37.5 Dead-Letter Queue Processing">Section 37.5, “Dead-Letter Queue Processing”</a>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When <span class="strong"><strong>multiple</strong></span> RabbitMQ binders are used in a Spring Cloud Stream application, it is important to disable 'RabbitAutoConfiguration' to avoid the same configuration from RabbitAutoConfiguration being applied to the two binders.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_configuration_options_3" href="#_configuration_options_3"></a>37.3 Configuration Options</h2></div></div></div><p>This section contains settings specific to the RabbitMQ Binder and bound channels.</p><p>For general binding configuration options and properties,
|
|
please refer to the <a class="link" href="https://github.com/spring-cloud/spring-cloud-stream/blob/master/spring-cloud-stream-docs/src/main/asciidoc/spring-cloud-stream-overview.adoc#configuration-options" target="_top">Spring Cloud Stream core documentation</a>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="rabbit-binder-properties" href="#rabbit-binder-properties"></a>37.3.1 RabbitMQ Binder Properties</h3></div></div></div><p>By default, the RabbitMQ binder uses Spring Boot’s <code class="literal">ConnectionFactory</code>, and it therefore supports all Spring Boot configuration options for RabbitMQ.
|
|
(For reference, consult the <a class="link" href="http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#common-application-properties" target="_top">Spring Boot documentation</a>.)
|
|
RabbitMQ configuration options use the <code class="literal">spring.rabbitmq</code> prefix.</p><p>In addition to Spring Boot options, the RabbitMQ binder supports the following properties:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">spring.cloud.stream.rabbit.binder.adminAddresses</span></dt><dd><p class="simpara"> A comma-separated list of RabbitMQ management plugin URLs.
|
|
Only used when <code class="literal">nodes</code> contains more than one entry.
|
|
Each entry in this list must have a corresponding entry in <code class="literal">spring.rabbitmq.addresses</code>.</p><p class="simpara">Default: empty.</p></dd><dt><span class="term">spring.cloud.stream.rabbit.binder.nodes</span></dt><dd><p class="simpara"> A comma-separated list of RabbitMQ node names.
|
|
When more than one entry, used to locate the server address where a queue is located.
|
|
Each entry in this list must have a corresponding entry in <code class="literal">spring.rabbitmq.addresses</code>.</p><p class="simpara">Default: empty.</p></dd><dt><span class="term">spring.cloud.stream.rabbit.binder.compressionLevel</span></dt><dd><p class="simpara"> Compression level for compressed bindings.
|
|
See <code class="literal">java.util.zip.Deflater</code>.</p><p class="simpara">Default: <code class="literal">1</code> (BEST_LEVEL).</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_rabbitmq_consumer_properties" href="#_rabbitmq_consumer_properties"></a>37.3.2 RabbitMQ Consumer Properties</h3></div></div></div><p>The following properties are available for Rabbit consumers only and
|
|
must be prefixed with <code class="literal">spring.cloud.stream.rabbit.bindings.<channelName>.consumer.</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">acknowledgeMode</span></dt><dd><p class="simpara">The acknowledge mode.</p><p class="simpara">Default: <code class="literal">AUTO</code>.</p></dd><dt><span class="term">autoBindDlq</span></dt><dd><p class="simpara">Whether to automatically declare the DLQ and bind it to the binder DLX.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">bindingRoutingKey</span></dt><dd><p class="simpara">The routing key with which to bind the queue to the exchange (if <code class="literal">bindQueue</code> is <code class="literal">true</code>).
|
|
for partitioned destinations <code class="literal">-<instanceIndex></code> will be appended.</p><p class="simpara">Default: <code class="literal">#</code>.</p></dd><dt><span class="term">bindQueue</span></dt><dd><p class="simpara">Whether to bind the queue to the destination exchange; set to <code class="literal">false</code> if you have set up your own infrastructure and have previously created/bound the queue.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">deadLetterQueueName</span></dt><dd><p class="simpara">name of the DLQ</p><p class="simpara">Default: <code class="literal">prefix+destination.dlq</code></p></dd><dt><span class="term">deadLetterExchange</span></dt><dd><p class="simpara">a DLX to assign to the queue; if autoBindDlq is true</p><p class="simpara">Default: 'prefix+DLX'</p></dd><dt><span class="term">deadLetterRoutingKey</span></dt><dd><p class="simpara">a dead letter routing key to assign to the queue; if autoBindDlq is true</p><p class="simpara">Default: <code class="literal">destination</code></p></dd><dt><span class="term">declareExchange</span></dt><dd><p class="simpara">Whether to declare the exchange for the destination.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">delayedExchange</span></dt><dd><p class="simpara">Whether to declare the exchange as a <code class="literal">Delayed Message Exchange</code> - requires the delayed message exchange plugin on the broker.
|
|
The <code class="literal">x-delayed-type</code> argument is set to the <code class="literal">exchangeType</code>.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">dlqDeadLetterExchange</span></dt><dd><p class="simpara">if a DLQ is declared, a DLX to assign to that queue</p><p class="simpara">Default: <code class="literal">none</code></p></dd><dt><span class="term">dlqDeadLetterRoutingKey</span></dt><dd><p class="simpara">if a DLQ is declared, a dead letter routing key to assign to that queue; default none</p><p class="simpara">Default: <code class="literal">none</code></p></dd><dt><span class="term">dlqExpires</span></dt><dd><p class="simpara">how long before an unused dead letter queue is deleted (ms)</p><p class="simpara">Default: <code class="literal">no expiration</code></p></dd><dt><span class="term">dlqMaxLength</span></dt><dd><p class="simpara">maximum number of messages in the dead letter queue</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">dlqMaxLengthBytes</span></dt><dd><p class="simpara">maximum number of total bytes in the dead letter queue from all messages</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">dlqMaxPriority</span></dt><dd><p class="simpara">maximum priority of messages in the dead letter queue (0-255)</p><p class="simpara">Default: <code class="literal">none</code></p></dd><dt><span class="term">dlqTtl</span></dt><dd><p class="simpara">default time to live to apply to the dead letter queue when declared (ms)</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">durableSubscription</span></dt><dd><p class="simpara"> Whether subscription should be durable.
|
|
Only effective if <code class="literal">group</code> is also set.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">exchangeAutoDelete</span></dt><dd><p class="simpara">If <code class="literal">declareExchange</code> is true, whether the exchange should be auto-delete (removed after the last queue is removed).</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">exchangeDurable</span></dt><dd><p class="simpara">If <code class="literal">declareExchange</code> is true, whether the exchange should be durable (survives broker restart).</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">exchangeType</span></dt><dd><p class="simpara">The exchange type; <code class="literal">direct</code>, <code class="literal">fanout</code> or <code class="literal">topic</code> for non-partitioned destinations; <code class="literal">direct</code> or <code class="literal">topic</code> for partitioned destinations.</p><p class="simpara">Default: <code class="literal">topic</code>.</p></dd><dt><span class="term">expires</span></dt><dd><p class="simpara">how long before an unused queue is deleted (ms)</p><p class="simpara">Default: <code class="literal">no expiration</code></p></dd><dt><span class="term">headerPatterns</span></dt><dd><p class="simpara">Patterns for headers to be mapped from inbound messages.</p><p class="simpara">Default: <code class="literal">['*']</code> (all headers).</p></dd><dt><span class="term">maxConcurrency</span></dt><dd><p class="simpara">the maximum number of consumers</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">maxLength</span></dt><dd><p class="simpara">maximum number of messages in the queue</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">maxLengthBytes</span></dt><dd><p class="simpara">maximum number of total bytes in the queue from all messages</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">maxPriority</span></dt><dd>maximum priority of messages in the queue (0-255)</dd><dt><span class="term">Default</span></dt><dd><code class="literal">none</code></dd><dt><span class="term">prefetch</span></dt><dd><p class="simpara">Prefetch count.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd><dt><span class="term">prefix</span></dt><dd><p class="simpara">A prefix to be added to the name of the <code class="literal">destination</code> and queues.</p><p class="simpara">Default: "".</p></dd><dt><span class="term">recoveryInterval</span></dt><dd><p class="simpara">The interval between connection recovery attempts, in milliseconds.</p><p class="simpara">Default: <code class="literal">5000</code>.</p></dd><dt><span class="term">requeueRejected</span></dt><dd><p class="simpara">Whether delivery failures should be requeued when retry is disabled or republishToDlq is false.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">republishDeliveryMode</span></dt><dd><p class="simpara">When <code class="literal">republishToDlq</code> is <code class="literal">true</code>, specify the delivery mode of the republished message.</p><p class="simpara">Default: <code class="literal">DeliveryMode.PERSISTENT</code></p></dd><dt><span class="term">republishToDlq</span></dt><dd><p class="simpara"> By default, messages which fail after retries are exhausted are rejected.
|
|
If a dead-letter queue (DLQ) is configured, RabbitMQ will route the failed message (unchanged) to the DLQ.
|
|
If set to <code class="literal">true</code>, the binder will republish failed messages to the DLQ with additional headers, including the exception message and stack trace from the cause of the final failure.</p><p class="simpara">Default: false</p></dd><dt><span class="term">transacted</span></dt><dd><p class="simpara">Whether to use transacted channels.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">ttl</span></dt><dd><p class="simpara">default time to live to apply to the queue when declared (ms)</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">txSize</span></dt><dd><p class="simpara">The number of deliveries between acks.</p><p class="simpara">Default: <code class="literal">1</code>.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_rabbit_producer_properties" href="#_rabbit_producer_properties"></a>37.3.3 Rabbit Producer Properties</h3></div></div></div><p>The following properties are available for Rabbit producers only and
|
|
must be prefixed with <code class="literal">spring.cloud.stream.rabbit.bindings.<channelName>.producer.</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">autoBindDlq</span></dt><dd><p class="simpara">Whether to automatically declare the DLQ and bind it to the binder DLX.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">batchingEnabled</span></dt><dd><p class="simpara">Whether to enable message batching by producers.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">batchSize</span></dt><dd><p class="simpara">The number of messages to buffer when batching is enabled.</p><p class="simpara">Default: <code class="literal">100</code>.</p></dd><dt><span class="term">batchBufferLimit</span></dt><dd>Default: <code class="literal">10000</code>.</dd><dt><span class="term">batchTimeout</span></dt><dd>Default: <code class="literal">5000</code>.</dd><dt><span class="term">bindingRoutingKey</span></dt><dd><p class="simpara">The routing key with which to bind the queue to the exchange (if <code class="literal">bindQueue</code> is <code class="literal">true</code>).
|
|
Only applies to non-partitioned destinations.
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">#</code>.</p></dd><dt><span class="term">bindQueue</span></dt><dd><p class="simpara">Whether to bind the queue to the destination exchange; set to <code class="literal">false</code> if you have set up your own infrastructure and have previously created/bound the queue.
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">compress</span></dt><dd><p class="simpara">Whether data should be compressed when sent.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">deadLetterQueueName</span></dt><dd><p class="simpara">name of the DLQ
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">prefix+destination.dlq</code></p></dd><dt><span class="term">deadLetterExchange</span></dt><dd><p class="simpara">a DLX to assign to the queue; if autoBindDlq is true
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: 'prefix+DLX'</p></dd><dt><span class="term">deadLetterRoutingKey</span></dt><dd><p class="simpara">a dead letter routing key to assign to the queue; if autoBindDlq is true
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">destination</code></p></dd><dt><span class="term">declareExchange</span></dt><dd><p class="simpara">Whether to declare the exchange for the destination.</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">delay</span></dt><dd><p class="simpara">A SpEL expression to evaluate the delay to apply to the message (<code class="literal">x-delay</code> header) - has no effect if the exchange is not a delayed message exchange.</p><p class="simpara">Default: No <code class="literal">x-delay</code> header is set.</p></dd><dt><span class="term">delayedExchange</span></dt><dd><p class="simpara">Whether to declare the exchange as a <code class="literal">Delayed Message Exchange</code> - requires the delayed message exchange plugin on the broker.
|
|
The <code class="literal">x-delayed-type</code> argument is set to the <code class="literal">exchangeType</code>.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">deliveryMode</span></dt><dd><p class="simpara">Delivery mode.</p><p class="simpara">Default: <code class="literal">PERSISTENT</code>.</p></dd><dt><span class="term">dlqDeadLetterExchange</span></dt><dd><p class="simpara">if a DLQ is declared, a DLX to assign to that queue
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">none</code></p></dd><dt><span class="term">dlqDeadLetterRoutingKey</span></dt><dd><p class="simpara">if a DLQ is declared, a dead letter routing key to assign to that queue; default none
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">none</code></p></dd><dt><span class="term">dlqExpires</span></dt><dd><p class="simpara">how long before an unused dead letter queue is deleted (ms)
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no expiration</code></p></dd><dt><span class="term">dlqMaxLength</span></dt><dd><p class="simpara">maximum number of messages in the dead letter queue
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">dlqMaxLengthBytes</span></dt><dd><p class="simpara">maximum number of total bytes in the dead letter queue from all messages
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">dlqMaxPriority</span></dt><dd><p class="simpara">maximum priority of messages in the dead letter queue (0-255)
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">none</code></p></dd><dt><span class="term">dlqTtl</span></dt><dd><p class="simpara">default time to live to apply to the dead letter queue when declared (ms)
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">exchangeAutoDelete</span></dt><dd><p class="simpara">If <code class="literal">declareExchange</code> is true, whether the exchange should be auto-delete (removed after the last queue is removed).</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">exchangeDurable</span></dt><dd><p class="simpara">If <code class="literal">declareExchange</code> is true, whether the exchange should be durable (survives broker restart).</p><p class="simpara">Default: <code class="literal">true</code>.</p></dd><dt><span class="term">exchangeType</span></dt><dd><p class="simpara">The exchange type; <code class="literal">direct</code>, <code class="literal">fanout</code> or <code class="literal">topic</code> for non-partitioned destinations; <code class="literal">direct</code> or <code class="literal">topic</code> for partitioned destinations.</p><p class="simpara">Default: <code class="literal">topic</code>.</p></dd><dt><span class="term">expires</span></dt><dd><p class="simpara">how long before an unused queue is deleted (ms)
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no expiration</code></p></dd><dt><span class="term">headerPatterns</span></dt><dd><p class="simpara">Patterns for headers to be mapped to outbound messages.</p><p class="simpara">Default: <code class="literal">['*']</code> (all headers).</p></dd><dt><span class="term">maxLength</span></dt><dd><p class="simpara">maximum number of messages in the queue
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">maxLengthBytes</span></dt><dd><p class="simpara">maximum number of total bytes in the queue from all messages
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd><dt><span class="term">maxPriority</span></dt><dd>maximum priority of messages in the queue (0-255)
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</dd><dt><span class="term">Default</span></dt><dd><code class="literal">none</code></dd><dt><span class="term">prefix</span></dt><dd><p class="simpara">A prefix to be added to the name of the <code class="literal">destination</code> exchange.</p><p class="simpara">Default: "".</p></dd><dt><span class="term">routingKeyExpression</span></dt><dd><p class="simpara">A SpEL expression to determine the routing key to use when publishing messages.</p><p class="simpara">Default: <code class="literal">destination</code> or <code class="literal">destination-<partition></code> for partitioned destinations.</p></dd><dt><span class="term">transacted</span></dt><dd><p class="simpara">Whether to use transacted channels.</p><p class="simpara">Default: <code class="literal">false</code>.</p></dd><dt><span class="term">ttl</span></dt><dd><p class="simpara">default time to live to apply to the queue when declared (ms)
|
|
Only applies if <code class="literal">requiredGroups</code> are provided and then only to those groups.</p><p class="simpara">Default: <code class="literal">no limit</code></p></dd></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>In the case of RabbitMQ, content type headers can be set by external applications.
|
|
Spring Cloud Stream supports them as part of an extended internal protocol used for any type of transport (including transports, such as Kafka, that do not normally support headers).</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_retry_with_the_rabbitmq_binder" href="#_retry_with_the_rabbitmq_binder"></a>37.4 Retry With the RabbitMQ Binder</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_overview" href="#_overview"></a>37.4.1 Overview</h3></div></div></div><p>When retry is enabled within the binder, the listener container thread is suspended for any back off periods that are configured.
|
|
This might be important when strict ordering is required with a single consumer but for other use cases it prevents other messages from being processed on that thread.
|
|
An alternative to using binder retry is to set up dead lettering with time to live on the dead-letter queue (DLQ), as well as dead-letter configuration on the DLQ itself.
|
|
See <a class="xref" href="#rabbit-binder-properties" title="37.3.1 RabbitMQ Binder Properties">Section 37.3.1, “RabbitMQ Binder Properties”</a> for more information about the properties discussed here.
|
|
Example configuration to enable this feature:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Set <code class="literal">autoBindDlq</code> to <code class="literal">true</code> - the binder will create a DLQ; you can optionally specify a name in <code class="literal">deadLetterQueueName</code></li><li class="listitem">Set <code class="literal">dlqTtl</code> to the back off time you want to wait between redeliveries</li><li class="listitem">Set the <code class="literal">dlqDeadLetterExchange</code> to the default exchange - expired messages from the DLQ will be routed to the original queue since the default <code class="literal">deadLetterRoutingKey</code> is the queue name (<code class="literal">destination.group</code>)</li></ul></div><p>To force a message to be dead-lettered, either throw an <code class="literal">AmqpRejectAndDontRequeueException</code>, or set <code class="literal">requeueRejected</code> to <code class="literal">true</code> and throw any exception.</p><p>The loop will continue without end, which is fine for transient problems but you may want to give up after some number of attempts.
|
|
Fortunately, RabbitMQ provides the <code class="literal">x-death</code> header which allows you to determine how many cycles have occurred.</p><p>To acknowledge a message after giving up, throw an <code class="literal">ImmediateAcknowledgeAmqpException</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_putting_it_all_together" href="#_putting_it_all_together"></a>37.4.2 Putting it All Together</h3></div></div></div><pre class="screen">---
|
|
spring.cloud.stream.bindings.input.destination=myDestination
|
|
spring.cloud.stream.bindings.input.group=consumerGroup
|
|
#disable binder retries
|
|
spring.cloud.stream.bindings.input.consumer.max-attempts=1
|
|
#dlx/dlq setup
|
|
spring.cloud.stream.rabbit.bindings.input.consumer.auto-bind-dlq=true
|
|
spring.cloud.stream.rabbit.bindings.input.consumer.dlq-ttl=5000
|
|
spring.cloud.stream.rabbit.bindings.input.consumer.dlq-dead-letter-exchange=
|
|
---</pre><p>This configuration creates an exchange <code class="literal">myDestination</code> with queue <code class="literal">myDestination.consumerGroup</code> bound to a topic exchange with a wildcard routing key <code class="literal">#</code>.
|
|
It creates a DLQ bound to a direct exchange <code class="literal">DLX</code> with routing key <code class="literal">myDestination.consumerGroup</code>.
|
|
When messages are rejected, they are routed to the DLQ.
|
|
After 5 seconds, the message expires and is routed to the original queue using the queue name as the routing key.</p><p><b>Spring Boot application. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableBinding(Sink.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> XDeathApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(XDeathApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@StreamListener(Sink.INPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> listen(String in, <em><span class="hl-annotation" style="color: gray">@Header(name = "x-death", required = false)</span></em> Map<?,?> death) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (death != null && death.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"count"</span>).equals(<span class="hl-number">3L</span>)) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// giving up - don't send to DLX</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throw</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ImmediateAcknowledgeAmqpException(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Failed after 4 attempts"</span>);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throw</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AmqpRejectAndDontRequeueException(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"failed"</span>);
|
|
}
|
|
|
|
}</pre><p>
|
|
</p><p>Notice that the count property in the <code class="literal">x-death</code> header is a <code class="literal">Long</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rabbit-dlq-processing" href="#rabbit-dlq-processing"></a>37.5 Dead-Letter Queue Processing</h2></div></div></div><p>Because it can’t be anticipated how users would want to dispose of dead-lettered messages, the framework does not provide any standard mechanism to handle them.
|
|
If the reason for the dead-lettering is transient, you may wish to route the messages back to the original queue.
|
|
However, if the problem is a permanent issue, that could cause an infinite loop.
|
|
The following <code class="literal">spring-boot</code> application is an example of how to route those messages back to the original queue, but moves them to a third "parking lot" queue after three attempts.
|
|
The second example utilizes the <a class="link" href="https://www.rabbitmq.com/blog/2015/04/16/scheduling-messages-with-rabbitmq/" target="_top">RabbitMQ Delayed Message Exchange</a> to introduce a delay to the requeued message.
|
|
In this example, the delay increases for each attempt.
|
|
These examples use a <code class="literal">@RabbitListener</code> to receive messages from the DLQ, you could also use <code class="literal">RabbitTemplate.receive()</code> in a batch process.</p><p>The examples assume the original destination is <code class="literal">so8400in</code> and the consumer group is <code class="literal">so8400</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_non_partitioned_destinations" href="#_non_partitioned_destinations"></a>37.5.1 Non-Partitioned Destinations</h3></div></div></div><p>The first two examples are when the destination is <span class="strong"><strong>not</strong></span> partitioned.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ReRouteDlqApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String ORIGINAL_QUEUE = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"so8400in.so8400"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String DLQ = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".dlq"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String PARKING_LOT = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".parkingLot"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_RETRIES_HEADER = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-retries"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
ConfigurableApplicationContext context = SpringApplication.run(ReRouteDlqApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hit enter to terminate"</span>);
|
|
System.in.read();
|
|
context.close();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RabbitTemplate rabbitTemplate;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RabbitListener(queues = DLQ)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> rePublish(Message failedMessage) {
|
|
Integer retriesHeader = (Integer) failedMessage.getMessageProperties().getHeaders().get(X_RETRIES_HEADER);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader == null) {
|
|
retriesHeader = Integer.valueOf(<span class="hl-number">0</span>);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader < <span class="hl-number">3</span>) {
|
|
failedMessage.getMessageProperties().getHeaders().put(X_RETRIES_HEADER, retriesHeader + <span class="hl-number">1</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(ORIGINAL_QUEUE, failedMessage);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">else</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(PARKING_LOT, failedMessage);
|
|
}
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Queue parkingLot() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Queue(PARKING_LOT);
|
|
}
|
|
|
|
}</pre><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ReRouteDlqApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String ORIGINAL_QUEUE = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"so8400in.so8400"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String DLQ = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".dlq"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String PARKING_LOT = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".parkingLot"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_RETRIES_HEADER = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-retries"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String DELAY_EXCHANGE = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"dlqReRouter"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
ConfigurableApplicationContext context = SpringApplication.run(ReRouteDlqApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hit enter to terminate"</span>);
|
|
System.in.read();
|
|
context.close();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RabbitTemplate rabbitTemplate;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RabbitListener(queues = DLQ)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> rePublish(Message failedMessage) {
|
|
Map<String, Object> headers = failedMessage.getMessageProperties().getHeaders();
|
|
Integer retriesHeader = (Integer) headers.get(X_RETRIES_HEADER);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader == null) {
|
|
retriesHeader = Integer.valueOf(<span class="hl-number">0</span>);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader < <span class="hl-number">3</span>) {
|
|
headers.put(X_RETRIES_HEADER, retriesHeader + <span class="hl-number">1</span>);
|
|
headers.put(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-delay"</span>, <span class="hl-number">5000</span> * retriesHeader);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(DELAY_EXCHANGE, ORIGINAL_QUEUE, failedMessage);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">else</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(PARKING_LOT, failedMessage);
|
|
}
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> DirectExchange delayExchange() {
|
|
DirectExchange exchange = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> DirectExchange(DELAY_EXCHANGE);
|
|
exchange.setDelayed(true);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> exchange;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Binding bindOriginalToDelay() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> BindingBuilder.bind(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Queue(ORIGINAL_QUEUE)).to(delayExchange()).with(ORIGINAL_QUEUE);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Queue parkingLot() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Queue(PARKING_LOT);
|
|
}
|
|
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_partitioned_destinations" href="#_partitioned_destinations"></a>37.5.2 Partitioned Destinations</h3></div></div></div><p>With partitioned destinations, there is one DLQ for all partitions and we determine the original queue from the headers.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_republishtodlq_false" href="#_republishtodlq_false"></a>republishToDlq=false</h4></div></div></div><p>When <code class="literal">republishToDlq</code> is <code class="literal">false</code>, RabbitMQ publishes the message to the DLX/DLQ with an <code class="literal">x-death</code> header containing information about the original destination.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ReRouteDlqApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String ORIGINAL_QUEUE = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"so8400in.so8400"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String DLQ = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".dlq"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String PARKING_LOT = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".parkingLot"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_DEATH_HEADER = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-death"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_RETRIES_HEADER = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-retries"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
ConfigurableApplicationContext context = SpringApplication.run(ReRouteDlqApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hit enter to terminate"</span>);
|
|
System.in.read();
|
|
context.close();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RabbitTemplate rabbitTemplate;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SuppressWarnings("unchecked")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RabbitListener(queues = DLQ)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> rePublish(Message failedMessage) {
|
|
Map<String, Object> headers = failedMessage.getMessageProperties().getHeaders();
|
|
Integer retriesHeader = (Integer) headers.get(X_RETRIES_HEADER);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader == null) {
|
|
retriesHeader = Integer.valueOf(<span class="hl-number">0</span>);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader < <span class="hl-number">3</span>) {
|
|
headers.put(X_RETRIES_HEADER, retriesHeader + <span class="hl-number">1</span>);
|
|
List<Map<String, ?>> xDeath = (List<Map<String, ?>>) headers.get(X_DEATH_HEADER);
|
|
String exchange = (String) xDeath.get(<span class="hl-number">0</span>).get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"exchange"</span>);
|
|
List<String> routingKeys = (List<String>) xDeath.get(<span class="hl-number">0</span>).get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"routing-keys"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(exchange, routingKeys.get(<span class="hl-number">0</span>), failedMessage);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">else</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(PARKING_LOT, failedMessage);
|
|
}
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Queue parkingLot() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Queue(PARKING_LOT);
|
|
}
|
|
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_republishtodlq_true" href="#_republishtodlq_true"></a>republishToDlq=true</h4></div></div></div><p>When <code class="literal">republishToDlq</code> is <code class="literal">true</code>, the republishing recoverer adds the original exchange and routing key to headers.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ReRouteDlqApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String ORIGINAL_QUEUE = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"so8400in.so8400"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String DLQ = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".dlq"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String PARKING_LOT = ORIGINAL_QUEUE + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".parkingLot"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_RETRIES_HEADER = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"x-retries"</span>;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_ORIGINAL_EXCHANGE_HEADER = RepublishMessageRecoverer.X_ORIGINAL_EXCHANGE;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> String X_ORIGINAL_ROUTING_KEY_HEADER = RepublishMessageRecoverer.X_ORIGINAL_ROUTING_KEY;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
ConfigurableApplicationContext context = SpringApplication.run(ReRouteDlqApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
System.out.println(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hit enter to terminate"</span>);
|
|
System.in.read();
|
|
context.close();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RabbitTemplate rabbitTemplate;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RabbitListener(queues = DLQ)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> rePublish(Message failedMessage) {
|
|
Map<String, Object> headers = failedMessage.getMessageProperties().getHeaders();
|
|
Integer retriesHeader = (Integer) headers.get(X_RETRIES_HEADER);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader == null) {
|
|
retriesHeader = Integer.valueOf(<span class="hl-number">0</span>);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (retriesHeader < <span class="hl-number">3</span>) {
|
|
headers.put(X_RETRIES_HEADER, retriesHeader + <span class="hl-number">1</span>);
|
|
String exchange = (String) headers.get(X_ORIGINAL_EXCHANGE_HEADER);
|
|
String originalRoutingKey = (String) headers.get(X_ORIGINAL_ROUTING_KEY_HEADER);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(exchange, originalRoutingKey, failedMessage);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">else</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.rabbitTemplate.send(PARKING_LOT, failedMessage);
|
|
}
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Queue parkingLot() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Queue(PARKING_LOT);
|
|
}
|
|
|
|
}</pre></div></div></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_bus" href="#_spring_cloud_bus"></a>Part VI. Spring Cloud Bus</h1></div></div></div><div class="partintro"><div></div><p>Spring Cloud Bus links nodes of a distributed system with a lightweight message broker. This can then be used to broadcast state changes (e.g. configuration changes) or other management instructions. A key idea is that the Bus is like a distributed Actuator for a Spring Boot application that is scaled out, but it can also be used as a communication channel between apps. Starters are provided for an AMQP broker as the transport or for Kafka, but the same basic feature set (and some more depending on the transport) is on the roadmap for other transports.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at <a class="link" href="https://github.com/spring-cloud/spring-cloud-config/tree/master/docs/src/main/asciidoc" target="_top">github</a>.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_quick_start_2" href="#_quick_start_2"></a>38. Quick Start</h2></div></div></div><p>Spring Cloud Bus works by adding Spring Boot autconfiguration if it detects itself on the classpath. All you need to do to enable the bus is to add <code class="literal">spring-cloud-starter-bus-amqp</code> or <code class="literal">spring-cloud-starter-bus-kafka</code> to your dependency management and Spring Cloud takes care of the rest. Make sure the broker (RabbitMQ or Kafka) is available and configured: running on localhost you shouldn’t have to do anything, but if you are running remotely use Spring Cloud Connectors, or Spring Boot conventions to define the broker credentials, e.g. for Rabbit</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
rabbitmq:
|
|
host: mybroker.com
|
|
port: 5672
|
|
username: user
|
|
password: secret</pre><p>
|
|
</p><p>The bus currently supports sending messages to all nodes listening or all nodes for a particular service (as defined by Eureka). More selector criteria may be added in the future (ie. only service X nodes in data center Y, etc…​). There are also some http endpoints under the <code class="literal">/bus/*</code> actuator namespace. There are currently two implemented. The first, <code class="literal">/bus/env</code>, sends key/value pairs to update each node’s Spring Environment. The second, <code class="literal">/bus/refresh</code>, will reload each application’s configuration, just as if they had all been pinged on their <code class="literal">/refresh</code> endpoint.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The Bus starters cover Rabbit and Kafka, because those are the two most common implementations, but Spring Cloud Stream is quite flexible and binder will work combined with <code class="literal">spring-cloud-bus</code>.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_addressing_an_instance" href="#_addressing_an_instance"></a>39. Addressing an Instance</h2></div></div></div><p>The HTTP endpoints accept a "destination" parameter, e.g. "/bus/refresh?destination=customers:9000", where the destination is an <code class="literal">ApplicationContext</code> ID. If the ID is owned by an instance on the Bus then it will process the message and all other instances will ignore it. Spring Boot sets the ID for you in the <code class="literal">ContextIdApplicationContextInitializer</code> to a combination of the <code class="literal">spring.application.name</code>, active profiles and <code class="literal">server.port</code> by default.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_addressing_all_instances_of_a_service" href="#_addressing_all_instances_of_a_service"></a>40. Addressing all instances of a service</h2></div></div></div><p>The "destination" parameter is used in a Spring <code class="literal">PathMatcher</code> (with the path separator as a colon <code class="literal">:</code>) to determine if an instance will process the message. Using the example from above, "/bus/refresh?destination=customers:**" will target all instances of the "customers" service regardless of the profiles and ports set as the <code class="literal">ApplicationContext</code> ID.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_application_context_id_must_be_unique" href="#_application_context_id_must_be_unique"></a>41. Application Context ID must be unique</h2></div></div></div><p>The bus tries to eliminate processing an event twice, once from the original <code class="literal">ApplicationEvent</code> and once from the queue. To do this, it checks the sending application context id againts the current application context id. If multiple instances of a service have the same application context id, events will not be processed. Running on a local machine, each service will be on a different port and that will be part of the application context id. Cloud Foundry supplies an index to differentiate. To ensure that the application context id is the unique, set <code class="literal">spring.application.index</code> to something unique for each instance of a service. For example, in lattice, set <code class="literal">spring.application.index=${INSTANCE_INDEX}</code> in application.properties (or bootstrap.properties if using configserver).</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_customizing_the_message_broker" href="#_customizing_the_message_broker"></a>42. Customizing the Message Broker</h2></div></div></div><p>Spring Cloud Bus uses
|
|
<a class="link" href="https://cloud.spring.io/spring-cloud-stream" target="_top">Spring Cloud Stream</a> to
|
|
broadcast the messages so to get messages to flow you only need to
|
|
include the binder implementation of your choice in the
|
|
classpath. There are convenient starters specifically for the bus with
|
|
AMQP (RabbitMQ) and Kafka
|
|
(<code class="literal">spring-cloud-starter-bus-[amqp,kafka]</code>). Generally speaking
|
|
Spring Cloud Stream relies on Spring Boot autoconfiguration
|
|
conventions for configuring middleware, so for instance the AMQP
|
|
broker address can be changed with <code class="literal">spring.rabbitmq.*</code>
|
|
configuration properties. Spring Cloud Bus has a handful of native
|
|
configuration properties in <code class="literal">spring.cloud.bus.*</code>
|
|
(e.g. <code class="literal">spring.cloud.bus.destination</code> is the name of the topic to use
|
|
the the externall middleware). Normally the defaults will suffice.</p><p>To lean more about how to customize the message broker settings
|
|
consult the Spring Cloud Stream documentation.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_tracing_bus_events" href="#_tracing_bus_events"></a>43. Tracing Bus Events</h2></div></div></div><p>Bus events (subclasses of <code class="literal">RemoteApplicationEvent</code>) can be traced by
|
|
setting <code class="literal">spring.cloud.bus.trace.enabled=true</code>. If you do this then the
|
|
Spring Boot <code class="literal">TraceRepository</code> (if it is present) will show each event
|
|
sent and all the acks from each service instance. Example (from the
|
|
<code class="literal">/trace</code> endpoint):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2015-11-26T10:24:44.411+0000"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"info"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"signal"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spring.cloud.bus.ack"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"type"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"RefreshRemoteApplicationEvent"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"id"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"c4d374b7-58ea-4928-a312-31984def293b"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"origin"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stores:8081"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"destination"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"*:**"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2015-11-26T10:24:41.864+0000"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"info"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"signal"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spring.cloud.bus.sent"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"type"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"RefreshRemoteApplicationEvent"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"id"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"c4d374b7-58ea-4928-a312-31984def293b"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"origin"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"customers:9000"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"destination"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"*:**"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"timestamp"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2015-11-26T10:24:41.862+0000"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"info"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"signal"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spring.cloud.bus.ack"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"type"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"RefreshRemoteApplicationEvent"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"id"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"c4d374b7-58ea-4928-a312-31984def293b"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"origin"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"customers:9000"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"destination"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"*:**"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>This trace shows that a <code class="literal">RefreshRemoteApplicationEvent</code> was sent from
|
|
<code class="literal">customers:9000</code>, broadcast to all services, and it was received
|
|
(acked) by <code class="literal">customers:9000</code> and <code class="literal">stores:8081</code>.</p><p>To handle the ack signals yourself you could add an <code class="literal">@EventListener</code>
|
|
for the <code class="literal">AckRemoteApplicationEvent</code> and <code class="literal">SentApplicationEvent</code> types
|
|
to your app (and enable tracing). Or you could tap into the
|
|
<code class="literal">TraceRepository</code> and mine the data from there.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Any Bus application can trace acks, but sometimes it will be
|
|
useful to do this in a central service that can do more complex
|
|
queries on the data. Or forward it to a specialized tracing service.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_broadcasting_your_own_events" href="#_broadcasting_your_own_events"></a>44. Broadcasting Your Own Events</h2></div></div></div><p>The Bus can carry any event of type <code class="literal">RemoteApplicationEvent</code>, but the
|
|
default transport is JSON and the deserializer needs to know which
|
|
types are going to be used ahead of time. To register a new type it
|
|
needs to be in a subpackage of <code class="literal">org.springframework.cloud.bus.event</code>.</p><p>To customise the event name you can use <code class="literal">@JsonTypeName</code> on your custom class
|
|
or rely on the default strategy which is to use the simple name of the class.
|
|
Note that both the producer and the consumer will need access to the class
|
|
definition.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_events_in_custom_packages" href="#_registering_events_in_custom_packages"></a>44.1 Registering events in custom packages</h2></div></div></div><p>If you cannot or don’t want to use a subpackage of <code class="literal">org.springframework.cloud.bus.event</code>
|
|
for your custom events, you must specify which packages to scan for events of
|
|
type <code class="literal">RemoteApplicationEvent</code> using <code class="literal">@RemoteApplicationEventScan</code>. Packages
|
|
specified with <code class="literal">@RemoteApplicationEventScan</code> include subpackages.</p><p>For example, if you have a custom event called <code class="literal">FooEvent</code>:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.acme;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> FooEvent <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> RemoteApplicationEvent {
|
|
...
|
|
}</pre><p>you can register this event with the deserializer in the following way:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.acme;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RemoteApplicationEventScan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> BusConfiguration {
|
|
...
|
|
}</pre><p>Without specifying a value, the package of the class where <code class="literal">@RemoteApplicationEventScan</code>
|
|
is used will be registered. In this example <code class="literal">com.acme</code> will be registered using the
|
|
package of <code class="literal">BusConfiguration</code>.</p><p>You can also explicitly specify the packages to scan using the <code class="literal">value</code>, <code class="literal">basePackages</code> or
|
|
<code class="literal">basePackageClasses</code> properties on <code class="literal">@RemoteApplicationEventScan</code>. For example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.acme;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//@RemoteApplicationEventScan({"com.acme", "foo.bar"})</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//@RemoteApplicationEventScan(basePackages = {"com.acme", "foo.bar", "fizz.buzz"})</span>
|
|
<em><span class="hl-annotation" style="color: gray">@RemoteApplicationEventScan(basePackageClasses = BusConfiguration.class)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> BusConfiguration {
|
|
...
|
|
}</pre><p>All examples of <code class="literal">@RemoteApplicationEventScan</code> above are equivalent,
|
|
in that the <code class="literal">com.acme</code> package will be registered by explicitly specifying the
|
|
packages on <code class="literal">@RemoteApplicationEventScan</code>. Note, you can specify multiple base
|
|
packages to scan.</p></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_sleuth" href="#_spring_cloud_sleuth"></a>Part VII. Spring Cloud Sleuth</h1></div></div></div><div class="partintro"><div></div><p>Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer</p><p><span class="strong"><strong>Dalston.SR4</strong></span></p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_introduction" href="#_introduction"></a>45. Introduction</h2></div></div></div><p>Spring Cloud Sleuth implements a distributed tracing solution for <a class="link" href="http://cloud.spring.io" target="_top">Spring Cloud</a>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_terminology" href="#_terminology"></a>45.1 Terminology</h2></div></div></div><p>Spring Cloud Sleuth borrows <a class="link" href="http://research.google.com/pubs/pub36356.html" target="_top">Dapper’s</a> terminology.</p><p><span class="strong"><strong>Span:</strong></span> The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an
|
|
RPC. Span’s are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span
|
|
is a part of. Spans also have other data, such as descriptions, timestamped events, key-value
|
|
annotations (tags), the ID of the span that caused them, and process ID’s (normally IP address).</p><p>Spans are started and stopped, and they keep track of their timing information. Once you create a
|
|
span, you must stop it at some point in the future.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>The initial span that starts a trace is called a <code class="literal">root span</code>. The value of span id
|
|
of that span is equal to trace id.</p></td></tr></table></div><p><span class="strong"><strong>Trace:</strong></span> A set of spans forming a tree-like structure. For example, if you are running a distributed
|
|
big-data store, a trace might be formed by a put request.</p><p><span class="strong"><strong>Annotation:</strong></span> is used to record existence of an event in time. Some of the core annotations used to define
|
|
the start and stop of a request are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>cs</strong></span> - Client Sent - The client has made a request. This annotation depicts the start of the span.</li><li class="listitem"><span class="strong"><strong>sr</strong></span> - Server Received - The server side got the request and will start processing it.
|
|
If one subtracts the cs timestamp from this timestamp one will receive the network latency.</li><li class="listitem"><span class="strong"><strong>ss</strong></span> - Server Sent - Annotated upon completion of request processing (when the response
|
|
got sent back to the client). If one subtracts the sr timestamp from this timestamp one
|
|
will receive the time needed by the server side to process the request.</li><li class="listitem"><span class="strong"><strong>cr</strong></span> - Client Received - Signifies the end of the span. The client has successfully received the
|
|
response from the server side. If one subtracts the cs timestamp from this timestamp one
|
|
will receive the whole time needed by the client to receive the response from the server.</li></ul></div><p>Visualization of what <span class="strong"><strong>Span</strong></span> and <span class="strong"><strong>Trace</strong></span> will look in a system together with the Zipkin annotations:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/trace-id.png" alt="Trace Info propagation"></div></div><p>Each color of a note signifies a span (7 spans - from <span class="strong"><strong>A</strong></span> to <span class="strong"><strong>G</strong></span>). If you have such information in the note:</p><pre class="screen">Trace Id = X
|
|
Span Id = D
|
|
Client Sent</pre><p>That means that the current span has <span class="strong"><strong>Trace-Id</strong></span> set to <span class="strong"><strong>X</strong></span>, <span class="strong"><strong>Span-Id</strong></span> set to <span class="strong"><strong>D</strong></span>. It also has emitted
|
|
<span class="strong"><strong>Client Sent</strong></span> event.</p><p>This is how the visualization of the parent / child relationship of spans would look like:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/parents.png" alt="Parent child relationship"></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_purpose" href="#_purpose"></a>45.2 Purpose</h2></div></div></div><p>In the following sections the example from the image above will be taken into consideration.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_distributed_tracing_with_zipkin" href="#_distributed_tracing_with_zipkin"></a>45.2.1 Distributed tracing with Zipkin</h3></div></div></div><p>Altogether there are <span class="strong"><strong>7 spans</strong></span> . If you go to traces in Zipkin you will see this number in the second trace:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-traces.png" alt="Traces"></div></div><p>However if you pick a particular trace then you will see <span class="strong"><strong>4 spans</strong></span>:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-ui.png" alt="Traces Info propagation"></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>When picking a particular trace you will see merged spans. That means that if there were 2 spans sent to
|
|
Zipkin with Server Received and Server Sent / Client Received and Client Sent
|
|
annotations then they will presented as a single span.</p></td></tr></table></div><p>Why is there a difference between the 7 and 4 spans in this case?</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">2 spans come from <code class="literal">http:/start</code> span. It has the Server Received (SR) and Server Sent (SS) annotations.</li><li class="listitem">2 spans come from the RPC call from <code class="literal">service1</code> to <code class="literal">service2</code> to the <code class="literal">http:/foo</code> endpoint. It has the Client Sent (CS)
|
|
and Client Received (CR) annotations on <code class="literal">service1</code> side. It also has Server Received (SR) and Server Sent (SS) annotations
|
|
on the <code class="literal">service2</code> side. Physically there are 2 spans but they form 1 logical span related to an RPC call.</li><li class="listitem">2 spans come from the RPC call from <code class="literal">service2</code> to <code class="literal">service3</code> to the <code class="literal">http:/bar</code> endpoint. It has the Client Sent (CS)
|
|
and Client Received (CR) annotations on <code class="literal">service2</code> side. It also has Server Received (SR) and Server Sent (SS) annotations
|
|
on the <code class="literal">service3</code> side. Physically there are 2 spans but they form 1 logical span related to an RPC call.</li><li class="listitem">2 spans come from the RPC call from <code class="literal">service2</code> to <code class="literal">service4</code> to the <code class="literal">http:/baz</code> endpoint. It has the Client Sent (CS)
|
|
and Client Received (CR) annotations on <code class="literal">service2</code> side. It also has Server Received (SR) and Server Sent (SS) annotations
|
|
on the <code class="literal">service4</code> side. Physically there are 2 spans but they form 1 logical span related to an RPC call.</li></ul></div><p>So if we count the physical spans we have <span class="strong"><strong>1</strong></span> from <code class="literal">http:/start</code>, <span class="strong"><strong>2</strong></span> from <code class="literal">service1</code> calling <code class="literal">service2</code>, <span class="strong"><strong>2</strong></span> form <code class="literal">service2</code>
|
|
calling <code class="literal">service3</code> and <span class="strong"><strong>2</strong></span> from <code class="literal">service2</code> calling <code class="literal">service4</code>. Altogether <span class="strong"><strong>7</strong></span> spans.</p><p>Logically we see the information of <span class="strong"><strong>Total Spans: 4</strong></span> because we have <span class="strong"><strong>1</strong></span> span related to the incoming request
|
|
to <code class="literal">service1</code> and <span class="strong"><strong>3</strong></span> spans related to RPC calls.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_visualizing_errors" href="#_visualizing_errors"></a>45.2.2 Visualizing errors</h3></div></div></div><p>Zipkin allows you to visualize errors in your trace. When an exception was thrown and wasn’t caught then we’re
|
|
setting proper tags on the span which Zipkin can properly colorize. You could see in the list of traces one
|
|
trace that was in red color. That’s because there was an exception thrown.</p><p>If you click that trace then you’ll see a similar picture</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-error-traces.png" alt="Error Traces"></div></div><p>Then if you click on one of the spans you’ll see the following</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/zipkin-error-trace-screenshot.png" alt="Error Traces Info propagation"></div></div><p>As you can see you can easily see the reason for an error and the whole stacktrace related to it.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_live_examples" href="#_live_examples"></a>45.2.3 Live examples</h3></div></div></div><div class="figure"><a name="d0e11224" href="#d0e11224"></a><p class="title"><b>Figure 45.1. Click Pivotal Web Services icon to see it live!</b></p><div class="figure-contents"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/pws.png" alt="Zipkin deployed on Pivotal Web Services"></div></div></div><br class="figure-break"><p>The dependency graph in Zipkin would look like this:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/dependencies.png" alt="Dependencies"></div></div><div class="figure"><a name="d0e11242" href="#d0e11242"></a><p class="title"><b>Figure 45.2. Click Pivotal Web Services icon to see it live!</b></p><div class="figure-contents"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/pws.png" alt="Zipkin deployed on Pivotal Web Services"></div></div></div><br class="figure-break"></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_log_correlation" href="#_log_correlation"></a>45.2.4 Log correlation</h3></div></div></div><p>When grepping the logs of those four applications by trace id equal to e.g. <code class="literal">2485ec27856c56f4</code> one would get the following:</p><pre class="screen">service1.log:2016-02-26 11:15:47.561 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Hello from service1. Calling service2
|
|
service2.log:2016-02-26 11:15:47.710 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Hello from service2. Calling service3 and then service4
|
|
service3.log:2016-02-26 11:15:47.895 INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application : Hello from service3
|
|
service2.log:2016-02-26 11:15:47.924 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Got response from service3 [Hello from service3]
|
|
service4.log:2016-02-26 11:15:48.134 INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application : Hello from service4
|
|
service2.log:2016-02-26 11:15:48.156 INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application : Got response from service4 [Hello from service4]
|
|
service1.log:2016-02-26 11:15:48.182 INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]</pre><p>If you’re using a log aggregating tool like <a class="link" href="https://www.elastic.co/products/kibana" target="_top">Kibana</a>,
|
|
<a class="link" href="http://www.splunk.com/" target="_top">Splunk</a> etc. you can order the events that took place. An example of
|
|
Kibana would look like this:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/master/docs/src/main/asciidoc/images/kibana.png" alt="Log correlation with Kibana"></div></div><p>If you want to use <a class="link" href="https://www.elastic.co/guide/en/logstash/current/index.html" target="_top">Logstash</a> here is the Grok pattern for Logstash:</p><pre class="screen">filter {
|
|
# pattern matching logback pattern
|
|
grok {
|
|
match => { "message" => "%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
|
|
}
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you want to use Grok together with the logs from Cloud Foundry you have to use this pattern:</p></td></tr></table></div><pre class="screen">filter {
|
|
# pattern matching logback pattern
|
|
grok {
|
|
match => { "message" => "(?m)OUT\s+%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}\s+---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
|
|
}
|
|
}</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_json_logback_with_logstash" href="#_json_logback_with_logstash"></a>JSON Logback with Logstash</h4></div></div></div><p>Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability
|
|
we’re passing the dependencies in the <code class="literal">groupId:artifactId:version</code> notation.</p><p><span class="strong"><strong>Dependencies setup</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Ensure that Logback is on the classpath (<code class="literal">ch.qos.logback:logback-core</code>)</li><li class="listitem">Add Logstash Logback encode - example for version <code class="literal">4.6</code> : <code class="literal">net.logstash.logback:logstash-logback-encoder:4.6</code></li></ul></div><p><span class="strong"><strong>Logback setup</strong></span></p><p>Below you can find an example of a Logback configuration (file named <a class="link" href="https://github.com/spring-cloud-samples/sleuth-documentation-apps/blob/master/service1/src/main/resources/logback-spring.xml" target="_top">logback-spring.xml</a>) that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">logs information from the application in a JSON format to a <code class="literal">build/${spring.application.name}.json</code> file</li><li class="listitem">has commented out two additional appenders - console and standard log file</li><li class="listitem">has the same logging pattern as the one presented in the previous section</li></ul></div><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">resource</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"org/springframework/boot/logging/logback/defaults.xml"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><springProperty</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">scope</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"context"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"springAppName"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">source</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"spring.application.name"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Example for logging into the build folder of your project --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><property</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"LOG_FILE"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">value</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"${BUILD_FOLDER:-build}/${springAppName}"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>​
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- You can override this to have a custom pattern --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><property</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"CONSOLE_LOG_PATTERN"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">value</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Appender to log to console --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"console"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.ConsoleAppender"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><filter</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.classic.filter.ThresholdFilter"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Minimum logging level to be presented in the console logs--></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><level></span>DEBUG<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></level></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></filter></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>${CONSOLE_LOG_PATTERN}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><charset></span>utf8<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></charset></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></appender></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Appender to log to file --></span>​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"flatfile"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><file></span>${LOG_FILE}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></file></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><rollingPolicy</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.TimeBasedRollingPolicy"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileNamePattern></span>${LOG_FILE}.%d{yyyy-MM-dd}.gz<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileNamePattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><maxHistory></span>7<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></maxHistory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></rollingPolicy></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>${CONSOLE_LOG_PATTERN}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><charset></span>utf8<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></charset></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></appender></span>
|
|
​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Appender to log to file in a JSON format --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">name</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"logstash"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.RollingFileAppender"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><file></span>${LOG_FILE}.json<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></file></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><rollingPolicy</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"ch.qos.logback.core.rolling.TimeBasedRollingPolicy"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileNamePattern></span>${LOG_FILE}.json.%d{yyyy-MM-dd}.gz<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileNamePattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><maxHistory></span>7<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></maxHistory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></rollingPolicy></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><encoder</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">class</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><providers></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><timestamp></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><timeZone></span>UTC<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></timeZone></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></timestamp></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pattern></span>
|
|
{
|
|
"severity": "%level",
|
|
"service": "${springAppName:-}",
|
|
"trace": "%X{X-B3-TraceId:-}",
|
|
"span": "%X{X-B3-SpanId:-}",
|
|
"parent": "%X{X-B3-ParentSpanId:-}",
|
|
"exportable": "%X{X-Span-Export:-}",
|
|
"pid": "${PID:-}",
|
|
"thread": "%thread",
|
|
"class": "%logger{40}",
|
|
"rest": "%message"
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pattern></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></providers></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></encoder></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></appender></span>
|
|
​
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><root</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">level</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"INFO"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><appender-ref</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">ref</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"console"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- uncomment this to have also JSON logs --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!--<appender-ref ref="logstash"/>--></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!--<appender-ref ref="flatfile"/>--></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></root></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span></pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you’re using a custom <code class="literal">logback-spring.xml</code> then you have to pass the <code class="literal">spring.application.name</code> in
|
|
<code class="literal">bootstrap</code> instead of <code class="literal">application</code> property file. Otherwise your custom logback file won’t read the property properly.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_propagating_span_context" href="#_propagating_span_context"></a>45.2.5 Propagating Span Context</h3></div></div></div><p>The span context is the state that must get propagated to any child Spans across process boundaries.
|
|
Part of the Span Context is the Baggage. The trace and span IDs are a required part of the span context.
|
|
Baggage is an optional part.</p><p>Baggage is a set of key:value pairs stored in the span context. Baggage travels together with the trace
|
|
and is attached to every span. Spring Cloud Sleuth will understand that a header is baggage related if the HTTP
|
|
header is prefixed with <code class="literal">baggage-</code> and for messaging it starts with <code class="literal">baggage_</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>There’s currently no limitation of the count or size of baggage items. However, keep in mind that
|
|
too many can decrease system throughput or increase RPC latency. In extreme cases, it could crash the app due
|
|
to exceeding transport-level message or header capacity.</p></td></tr></table></div><p>Example of setting baggage on a span:</p><pre class="programlisting">Span initialSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.createSpan(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"span"</span>);
|
|
initialSpan.setBaggageItem(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>);
|
|
initialSpan.setBaggageItem(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"UPPER_CASE"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"someValue"</span>);</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_baggage_vs_span_tags" href="#_baggage_vs_span_tags"></a>Baggage vs. Span Tags</h4></div></div></div><p>Baggage travels with the trace (i.e. every child span contains the baggage of its parent). Zipkin has no knowledge of
|
|
baggage and will not even receive that information.</p><p>Tags are attached to a specific span - they are presented for that particular span only. However you
|
|
can search by tag to find the trace, where there exists a span having the searched tag value.</p><p>If you want to be able to lookup a span based on baggage, you should add corresponding entry as a tag in the root span.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Autowired</span></em> Tracer tracer;
|
|
|
|
Span span = tracer.getCurrentSpan();
|
|
String baggageKey = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"key"</span>;
|
|
String baggageValue = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>;
|
|
span.setBaggageItem(baggageKey, baggageValue);
|
|
tracer.addTag(baggageKey, baggageValue);</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_adding_to_the_project" href="#_adding_to_the_project"></a>45.3 Adding to the project</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_only_sleuth_log_correlation" href="#_only_sleuth_log_correlation"></a>45.3.1 Only Sleuth (log correlation)</h3></div></div></div><p>If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add
|
|
the <code class="literal">spring-cloud-starter-sleuth</code> module to your project.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span> <a name="CO1-1" href="#CO1-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${release.train.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO1-2" href="#CO1-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-sleuth<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO1-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO1-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code></p></td></tr></table></div><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">dependencyManagement { <a name="CO2-1" href="#CO2-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies { <a name="CO2-2" href="#CO2-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-sleuth"</span>
|
|
}</pre><p class="secondary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO2-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO2-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sleuth_with_zipkin_via_http" href="#_sleuth_with_zipkin_via_http"></a>45.3.2 Sleuth with Zipkin via HTTP</h3></div></div></div><p>If you want both Sleuth and Zipkin just add the <code class="literal">spring-cloud-starter-zipkin</code> dependency.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span> <a name="CO3-1" href="#CO3-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${release.train.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO3-2" href="#CO3-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-zipkin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO3-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO3-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-zipkin</code></p></td></tr></table></div><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">dependencyManagement { <a name="CO4-1" href="#CO4-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies { <a name="CO4-2" href="#CO4-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-zipkin"</span>
|
|
}</pre><p class="secondary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO4-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO4-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-zipkin</code></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_sleuth_with_zipkin_via_spring_cloud_stream" href="#_sleuth_with_zipkin_via_spring_cloud_stream"></a>45.3.3 Sleuth with Zipkin via Spring Cloud Stream</h3></div></div></div><p>If you want both Sleuth and Zipkin just add the <code class="literal">spring-cloud-sleuth-stream</code> dependency.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span> <a name="CO5-1" href="#CO5-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${release.train.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO5-2" href="#CO5-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-sleuth-stream<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO5-3" href="#CO5-3"></a><span><img src="images/callouts/3.png" alt="3" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-sleuth<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- EXAMPLE FOR RABBIT BINDING --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO5-4" href="#CO5-4"></a><span><img src="images/callouts/4.png" alt="4" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-binder-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO5-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO5-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-sleuth-stream</code></p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO5-3"><span><img src="images/callouts/3.png" alt="3" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO5-4"><span><img src="images/callouts/4.png" alt="4" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p></td></tr></table></div><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">dependencyManagement { <a name="CO6-1" href="#CO6-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies {
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-sleuth-stream"</span> <a name="CO6-2" href="#CO6-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-sleuth"</span> <a name="CO6-3" href="#CO6-3"></a><span><img src="images/callouts/3.png" alt="3" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Example for Rabbit binding</span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-stream-binder-rabbit"</span> <a name="CO6-4" href="#CO6-4"></a><span><img src="images/callouts/4.png" alt="4" border="0"></span>
|
|
}</pre><p class="secondary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO6-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO6-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-sleuth-stream</code></p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO6-3"><span><img src="images/callouts/3.png" alt="3" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO6-4"><span><img src="images/callouts/4.png" alt="4" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spring_cloud_sleuth_stream_zipkin_collector" href="#_spring_cloud_sleuth_stream_zipkin_collector"></a>45.3.4 Spring Cloud Sleuth Stream Zipkin Collector</h3></div></div></div><p>If you want to start a Spring Cloud Sleuth Stream Zipkin collector just add the <code class="literal">spring-cloud-sleuth-zipkin-stream</code>
|
|
dependency</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span> <a name="CO7-1" href="#CO7-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${release.train.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO7-2" href="#CO7-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-sleuth-zipkin-stream<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO7-3" href="#CO7-3"></a><span><img src="images/callouts/3.png" alt="3" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-sleuth<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- EXAMPLE FOR RABBIT BINDING --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span> <a name="CO7-4" href="#CO7-4"></a><span><img src="images/callouts/4.png" alt="4" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-binder-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO7-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO7-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-sleuth-zipkin-stream</code></p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO7-3"><span><img src="images/callouts/3.png" alt="3" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO7-4"><span><img src="images/callouts/4.png" alt="4" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p></td></tr></table></div><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">dependencyManagement { <a name="CO8-1" href="#CO8-1"></a><span><img src="images/callouts/1.png" alt="1" border="0"></span>
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-dependencies:${releaseTrainVersion}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies {
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-sleuth-zipkin-stream"</span> <a name="CO8-2" href="#CO8-2"></a><span><img src="images/callouts/2.png" alt="2" border="0"></span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-sleuth"</span> <a name="CO8-3" href="#CO8-3"></a><span><img src="images/callouts/3.png" alt="3" border="0"></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Example for Rabbit binding</span>
|
|
compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-stream-binder-rabbit"</span> <a name="CO8-4" href="#CO8-4"></a><span><img src="images/callouts/4.png" alt="4" border="0"></span>
|
|
}</pre><p class="secondary">
|
|
</p><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#CO8-1"><span><img src="images/callouts/1.png" alt="1" border="0"></span></a> </p></td><td valign="top" align="left"><p>In order not to pick versions by yourself it’s much better if you add the dependency management via
|
|
the Spring BOM</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO8-2"><span><img src="images/callouts/2.png" alt="2" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-sleuth-zipkin-stream</code></p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO8-3"><span><img src="images/callouts/3.png" alt="3" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add the dependency to <code class="literal">spring-cloud-starter-sleuth</code> - that way all dependant dependencies will be downloaded</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#CO8-4"><span><img src="images/callouts/4.png" alt="4" border="0"></span></a> </p></td><td valign="top" align="left"><p>Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to</p></td></tr></table></div><p>and then just annotate your main class with <code class="literal">@EnableZipkinStreamServer</code> annotation:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> example;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.boot.SpringApplication;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.boot.autoconfigure.SpringBootApplication;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.sleuth.zipkin.stream.EnableZipkinStreamServer;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableZipkinStreamServer</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ZipkinStreamServerApplication {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
SpringApplication.run(ZipkinStreamServerApplication.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
|
|
}</pre></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_additional_resources" href="#_additional_resources"></a>46. Additional resources</h2></div></div></div><p><span class="strong"><strong>Marcin Grzejszczak talking about Spring Cloud Sleuth and Zipkin</strong></span></p><p><a class="link" href="https://www.youtube.com/watch?v=eQV71Mw1u1c" target="_top">click here to see the video</a></p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_features_2" href="#_features_2"></a>47. Features</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">Adds trace and span ids to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator. Example logs:</p><pre class="screen">2016-02-02 15:30:57.902 INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
|
|
2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
|
|
2016-02-02 15:31:01.936 INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ...</pre><p class="simpara">notice the <code class="literal">[appname,traceId,spanId,exportable]</code> entries from the MDC:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><span class="strong"><strong>spanId</strong></span> - the id of a specific operation that took place</li><li class="listitem"><span class="strong"><strong>appname</strong></span> - the name of the application that logged the span</li><li class="listitem"><span class="strong"><strong>traceId</strong></span> - the id of the latency graph that contains the span</li><li class="listitem"><span class="strong"><strong>exportable</strong></span> - whether the log should be exported to Zipkin or not. When would you like the span not to be
|
|
exportable? In the case in which you want to wrap some operation in a Span and have it written to the logs
|
|
only.</li></ul></div></li><li class="listitem">Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations,
|
|
key-value annotations. Loosely based on HTrace, but Zipkin (Dapper) compatible.</li><li class="listitem"><p class="simpara">Sleuth records timing information to aid in latency analysis. Using sleuth, you can pinpoint causes of
|
|
latency in your applications. Sleuth is written to not log too much, and to not cause your production application to crash.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">propagates structural data about your call-graph in-band, and the rest out-of-band.</li><li class="listitem">includes opinionated instrumentation of layers such as HTTP</li><li class="listitem">includes sampling policy to manage volume</li><li class="listitem">can report to a Zipkin system for query and visualization</li></ul></div></li><li class="listitem">Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints,
|
|
rest template, scheduled actions, message channels, zuul filters, feign client).</li><li class="listitem">Sleuth includes default logic to join a trace across http or messaging boundaries. For example, http propagation
|
|
works via Zipkin-compatible request headers. This propagation logic is defined and customized via
|
|
<code class="literal">SpanInjector</code> and <code class="literal">SpanExtractor</code> implementations.</li><li class="listitem">Sleuth gives you the possibility to propagate context (also known as baggage) between processes. That means that if you set on a Span
|
|
a baggage element then it will be sent downstream either via HTTP or messaging to other processes.</li><li class="listitem">Provides a way to create / continue spans and add tags and logs via annotations.</li><li class="listitem">Provides simple metrics of accepted / dropped spans.</li><li class="listitem">If <code class="literal">spring-cloud-sleuth-zipkin</code> then the app will generate and collect Zipkin-compatible traces.
|
|
By default it sends them via HTTP to a Zipkin server on localhost (port 9411).
|
|
Configure the location of the service using <code class="literal">spring.zipkin.baseUrl</code>.</li><li class="listitem">If <code class="literal">spring-cloud-sleuth-stream</code> then the app will generate and collect traces via <a class="link" href="https://github.com/spring-cloud/spring-cloud-stream" target="_top">Spring Cloud Stream</a>.
|
|
Your app automatically becomes a producer of tracer messages that are sent over your broker of choice
|
|
(e.g. RabbitMQ, Apache Kafka, Redis).</li></ul></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If using Zipkin or Stream, configure the percentage of spans exported using <code class="literal">spring.sleuth.sampler.percentage</code>
|
|
(default 0.1, i.e. 10%). <span class="strong"><strong>Otherwise you might think that Sleuth is not working cause it’s omitting some spans.</strong></span></p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the SLF4J MDC is always set and logback users will immediately see the trace and span ids in logs per the example
|
|
above. Other logging systems have to configure their own formatter to get the same result. The default is
|
|
<code class="literal">logging.pattern.level</code> set to <code class="literal">%5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}]</code>
|
|
(this is a Spring Boot feature for logback users).
|
|
<span class="strong"><strong>This means that if you’re not using SLF4J this pattern WILL NOT be automatically applied</strong></span>.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_sampling" href="#_sampling"></a>48. Sampling</h2></div></div></div><p>In distributed tracing the data volumes can be very high so sampling
|
|
can be important (you usually don’t need to export all spans to get a
|
|
good picture of what is happening). Spring Cloud Sleuth has a
|
|
<code class="literal">Sampler</code> strategy that you can implement to take control of the
|
|
sampling algorithm. Samplers do not stop span (correlation) ids from
|
|
being generated, but they do prevent the tags and events being
|
|
attached and exported. By default you get a strategy that continues to
|
|
trace if a span is already active, but new ones are always marked as
|
|
non-exportable. If all your apps run with this sampler you will see
|
|
traces in logs, but not in any remote store. For testing the default
|
|
is often enough, and it probably is all you need if you are only using
|
|
the logs (e.g. with an ELK aggregator). If you are exporting span data
|
|
to Zipkin or Spring Cloud Stream, there is also an <code class="literal">AlwaysSampler</code>
|
|
that exports everything and a <code class="literal">PercentageBasedSampler</code> that samples a
|
|
fixed fraction of spans.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the <code class="literal">PercentageBasedSampler</code> is the default if you are using
|
|
<code class="literal">spring-cloud-sleuth-zipkin</code> or <code class="literal">spring-cloud-sleuth-stream</code>. You can
|
|
configure the exports using <code class="literal">spring.sleuth.sampler.percentage</code>. The passed
|
|
value needs to be a double from <code class="literal">0.0</code> to <code class="literal">1.0</code> so it’s not a percentage.
|
|
For backwards compatibility reasons we’re not changing the property name.</p></td></tr></table></div><p>A sampler can be installed just by creating a bean definition, e.g:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Sampler defaultSampler() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AlwaysSampler();
|
|
}</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>You can set the HTTP header <code class="literal">X-B3-Flags</code> to <code class="literal">1</code> or when doing messaging you can
|
|
set <code class="literal">spanFlags</code> header to <code class="literal">1</code>. Then the current span will be forced to be exportable
|
|
regardless of the sampling decision.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_instrumentation" href="#_instrumentation"></a>49. Instrumentation</h2></div></div></div><p>Spring Cloud Sleuth instruments all your Spring application
|
|
automatically, so you shouldn’t have to do anything to activate
|
|
it. The instrumentation is added using a variety of technologies
|
|
according to the stack that is available, e.g. for a servlet web
|
|
application we use a <code class="literal">Filter</code>, and for Spring Integration we use
|
|
<code class="literal">ChannelInterceptors</code>.</p><p>You can customize the keys used in span tags. To limit the volume of
|
|
span data, by default an HTTP request will be tagged only with a
|
|
handful of metadata like the status code, host and URL. You can add
|
|
request headers by configuring <code class="literal">spring.sleuth.keys.http.headers</code> (a
|
|
list of header names).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Remember that tags are only collected and exported if there is a
|
|
<code class="literal">Sampler</code> that allows it (by default there is not, so there is no
|
|
danger of accidentally collecting too much data without configuring
|
|
something).</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Currently the instrumentation in Spring Cloud Sleuth is eager - it means that
|
|
we’re actively trying to pass the tracing context between threads. Also timing events
|
|
are captured even when sleuth isn’t exporting data to a tracing system.
|
|
This approach may change in the future towards being lazy on this matter.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_span_lifecycle" href="#_span_lifecycle"></a>50. Span lifecycle</h2></div></div></div><p>You can do the following operations on the Span by means of <span class="strong"><strong>org.springframework.cloud.sleuth.Tracer</strong></span> interface:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="#creating-and-closing-spans" title="50.1 Creating and closing spans">start</a> - when you start a span its name is assigned and start timestamp is recorded.</li><li class="listitem"><a class="link" href="#creating-and-closing-spans" title="50.1 Creating and closing spans">close</a> - the span gets finished (the end time of the span is recorded) and if
|
|
the span is <span class="strong"><strong>exportable</strong></span> then it will be eligible for collection to Zipkin.
|
|
The span is also removed from the current thread.</li><li class="listitem"><a class="link" href="#continuing-spans" title="50.2 Continuing spans">continue</a> - a new instance of span will be created whereas it will be a copy of the
|
|
one that it continues.</li><li class="listitem"><a class="link" href="#continuing-spans" title="50.2 Continuing spans">detach</a> - the span doesn’t get stopped or closed. It only gets removed from the current thread.</li><li class="listitem"><a class="link" href="#creating-spans-with-explicit-parent" title="50.3 Creating spans with an explicit parent">create with explicit parent</a> - you can create a new span and set an explicit parent to it</li></ul></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Spring creates the instance of <code class="literal">Tracer</code> for you. In order to use it all you need is to just autowire it.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="creating-and-closing-spans" href="#creating-and-closing-spans"></a>50.1 Creating and closing spans</h2></div></div></div><p>You can manually create spans by using the <span class="strong"><strong>Tracer</strong></span> interface.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Start a span. If there was a span present in this thread it will become</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the `newSpan`'s parent.</span>
|
|
Span newSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.createSpan(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can tag a span</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.addTag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxValue"</span>, taxValue);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can log an event on a span</span>
|
|
newSpan.logEvent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxCalculated"</span>);
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Once done remember to close the span. This will allow collecting</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the span to send it to Zipkin</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.close(newSpan);
|
|
}</pre><p>In this example we could see how to create a new instance of span. Assuming that there already
|
|
was a span present in this thread then it would become the parent of that span.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Always clean after you create a span! Don’t forget to close a span if you want to send it to Zipkin.</p></td></tr></table></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If your span contains a name greater than 50 chars, then that name will
|
|
be truncated to 50 chars. Your names have to be explicit and concrete. Big names lead to
|
|
latency issues and sometimes even thrown exceptions.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="continuing-spans" href="#continuing-spans"></a>50.2 Continuing spans</h2></div></div></div><p>Sometimes you don’t want to create a new span but you want to continue one. Example of such a
|
|
situation might be (of course it all depends on the use-case):</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>AOP</strong></span> - If there was already a span created before an aspect was reached then you might not want to create a new span.</li><li class="listitem"><span class="strong"><strong>Hystrix</strong></span> - executing a Hystrix command is most likely a logical part of the current processing. It’s in fact
|
|
only a technical implementation detail that you wouldn’t necessarily want to reflect in tracing as a separate being.</li></ul></div><p>The continued instance of span is equal to the one that it continues:</p><pre class="programlisting">Span continuedSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.continueSpan(spanToContinue);
|
|
assertThat(continuedSpan).isEqualTo(spanToContinue);</pre><p>To continue a span you can use the <span class="strong"><strong>Tracer</strong></span> interface.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// let's assume that we're in a thread Y and we've received</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the `initialSpan` from thread X</span>
|
|
Span continuedSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.continueSpan(initialSpan);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can tag a span</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.addTag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxValue"</span>, taxValue);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can log an event on a span</span>
|
|
continuedSpan.logEvent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"taxCalculated"</span>);
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Once done remember to detach the span. That way you'll</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// safely remove it from the current thread without closing it</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.detach(continuedSpan);
|
|
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Always clean after you create a span! Don’t forget to detach a span if some work was done started in one
|
|
thread (e.g. thread X) and it’s waiting for other threads (e.g. Y, Z) to finish.
|
|
Then the spans in the threads Y, Z should be detached at the end of their work. When the results are collected
|
|
the span in thread X should be closed.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="creating-spans-with-explicit-parent" href="#creating-spans-with-explicit-parent"></a>50.3 Creating spans with an explicit parent</h2></div></div></div><p>There is a possibility that you want to start a new span and provide an explicit parent of that span.
|
|
Let’s assume that the parent of a span is in one thread and you want to start a new span in another thread. The
|
|
<code class="literal">startSpan</code> method of the <code class="literal">Tracer</code> interface is the method you are looking for.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// let's assume that we're in a thread Y and we've received</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the `initialSpan` from thread X. `initialSpan` will be the parent</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// of the `newSpan`</span>
|
|
Span newSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.createSpan(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateCommission"</span>, initialSpan);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can tag a span</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.addTag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"commissionValue"</span>, commissionValue);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ...</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// You can log an event on a span</span>
|
|
newSpan.logEvent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"commissionCalculated"</span>);
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Once done remember to close the span. This will allow collecting</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the span to send it to Zipkin. The tags and events set on the</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// newSpan will not be present on the parent</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.close(newSpan);
|
|
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>After having created such a span remember to close it. Otherwise you will see a lot of warnings in your logs
|
|
related to the fact that you have a span present in the current thread other than the one you’re trying to close.
|
|
What’s worse your spans won’t get closed properly thus will not get collected to Zipkin.</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_naming_spans" href="#_naming_spans"></a>51. Naming spans</h2></div></div></div><p>Picking a span name is not a trivial task. Span name should depict an operation name. The name should
|
|
be low cardinality (e.g. not include identifiers).</p><p>Since there is a lot of instrumentation going on some of the span names will be
|
|
artificial like:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">controller-method-name</code> when received by a Controller with a method name <code class="literal">conrollerMethodName</code></li><li class="listitem"><code class="literal">async</code> for asynchronous operations done via wrapped <code class="literal">Callable</code> and <code class="literal">Runnable</code>.</li><li class="listitem"><code class="literal">@Scheduled</code> annotated methods will return the simple name of the class.</li></ul></div><p>Fortunately, for the asynchronous processing you can provide explicit naming.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="__spanname_annotation" href="#__spanname_annotation"></a>51.1 @SpanName annotation</h2></div></div></div><p>You can name the span explicitly via the <code class="literal">@SpanName</code> annotation.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpanName("calculateTax")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TaxCountingRunnable <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> Runnable {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> run() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// perform logic</span>
|
|
}
|
|
}</pre><p>In this case, when processed in the following manner:</p><pre class="programlisting">Runnable runnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceRunnable(tracer, spanNamer, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TaxCountingRunnable());
|
|
Future<?> future = executorService.submit(runnable);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ... some additional logic ...</span>
|
|
future.get();</pre><p>The span will be named <code class="literal">calculateTax</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_tostring_method" href="#_tostring_method"></a>51.2 toString() method</h2></div></div></div><p>It’s pretty rare to create separate classes for <code class="literal">Runnable</code> or <code class="literal">Callable</code>. Typically one creates an anonymous
|
|
instance of those classes. You can’t annotate such classes thus to override that, if there is no <code class="literal">@SpanName</code> annotation present,
|
|
we’re checking if the class has a custom implementation of the <code class="literal">toString()</code> method.</p><p>So executing such code:</p><pre class="programlisting">Runnable runnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceRunnable(tracer, spanNamer, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Runnable() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> run() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// perform logic</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String toString() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>;
|
|
}
|
|
});
|
|
Future<?> future = executorService.submit(runnable);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ... some additional logic ...</span>
|
|
future.get();</pre><p>will lead in creating a span named <code class="literal">calculateTax</code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_managing_spans_with_annotations" href="#_managing_spans_with_annotations"></a>52. Managing spans with annotations</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_rationale" href="#_rationale"></a>52.1 Rationale</h2></div></div></div><p>The main arguments for this features are</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">api-agnostic means to collaborate with a span</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">use of annotations allows users to add to a span with no library dependency on a span api.
|
|
This allows Sleuth to change its core api less impact to user code.</li></ul></div></li><li class="listitem"><p class="simpara">reduced surface area for basic span operations.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">without this feature one has to use the span api, which has lifecycle commands that
|
|
could be used incorrectly. By only exposing scope, tag and log functionality, users can
|
|
collaborate without accidentally breaking span lifecycle.</li></ul></div></li><li class="listitem"><p class="simpara">collaboration with runtime generated code</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">with libraries such as Spring Data / Feign the implementations of interfaces are generated
|
|
at runtime thus span wrapping of objects was tedious. Now you can provide annotations
|
|
over interfaces and arguments of those interfaces</li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_creating_new_spans" href="#_creating_new_spans"></a>52.2 Creating new spans</h2></div></div></div><p>If you really don’t want to take care of creating local spans manually you can profit from the
|
|
<code class="literal">@NewSpan</code> annotation. Also we give you the <code class="literal">@SpanTag</code> annotation to add tags in an automated
|
|
fashion.</p><p>Let’s look at some examples of usage.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod();</pre><p>Annotating the method without any parameter will lead to a creation of a new span whose name
|
|
will be equal to annotated method name.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan("customNameOnTestMethod4")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod4();</pre><p>If you provide the value in the annotation (either directly or via the <code class="literal">name</code> parameter) then
|
|
the created span will have the name as the provided value.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// method declaration</span>
|
|
<em><span class="hl-annotation" style="color: gray">@NewSpan(name = "customNameOnTestMethod5")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod5(<em><span class="hl-annotation" style="color: gray">@SpanTag("testTag")</span></em> String param);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and method execution</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.testBean.testMethod5(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"test"</span>);</pre><p>You can combine both the name and a tag. Let’s focus on the latter. In this case whatever the value of
|
|
the annotated method’s parameter runtime value will be - that will be the value of the tag. In our sample
|
|
the tag key will be <code class="literal">testTag</code> and the tag value will be <code class="literal">test</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan(name = "customNameOnTestMethod3")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod3() {
|
|
}</pre><p>You can place the <code class="literal">@NewSpan</code> annotation on both the class and an interface. If you override the
|
|
interface’s method and provide a different value of the <code class="literal">@NewSpan</code> annotation then the most
|
|
concrete one wins (in this case <code class="literal">customNameOnTestMethod3</code> will be set).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_continuing_spans" href="#_continuing_spans"></a>52.3 Continuing spans</h2></div></div></div><p>If you want to just add tags and annotations to an existing span it’s enough
|
|
to use the <code class="literal">@ContinueSpan</code> annotation as presented below. Note that in contrast
|
|
with the <code class="literal">@NewSpan</code> annotation you can also add logs via the <code class="literal">log</code> parameter:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// method declaration</span>
|
|
<em><span class="hl-annotation" style="color: gray">@ContinueSpan(log = "testMethod11")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> testMethod11(<em><span class="hl-annotation" style="color: gray">@SpanTag("testTag11")</span></em> String param);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// method execution</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.testBean.testMethod11(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"test"</span>);</pre><p>That way the span will get continued and:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">logs with name <code class="literal">testMethod11.before</code> and <code class="literal">testMethod11.after</code> will be created</li><li class="listitem">if an exception will be thrown a log <code class="literal">testMethod11.afterFailure</code> will also be created</li><li class="listitem">tag with key <code class="literal">testTag11</code> and value <code class="literal">test</code> will be created</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_more_advanced_tag_setting" href="#_more_advanced_tag_setting"></a>52.4 More advanced tag setting</h2></div></div></div><p>There are 3 different ways to add tags to a span. All of them are controlled by the <code class="literal">SpanTag</code> annotation.
|
|
Precedence is:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">try with the bean of <code class="literal">TagValueResolver</code> type and provided name</li><li class="listitem">if one hasn’t provided the bean name, try to evaluate an expression. We’re searching for a <code class="literal">TagValueExpressionResolver</code> bean.
|
|
The default implementation uses SPEL expression resolution.</li><li class="listitem">if one hasn’t provided any expression to evaluate just return a <code class="literal">toString()</code> value of the parameter</li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_custom_extractor" href="#_custom_extractor"></a>52.4.1 Custom extractor</h3></div></div></div><p>The value of the tag for following method will be computed by an implementation of <code class="literal">TagValueResolver</code> interface.
|
|
Its class name has to be passed as the value of the <code class="literal">resolver</code> attribute.</p><p>Having such an annotated method:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> getAnnotationForTagValueResolver(<em><span class="hl-annotation" style="color: gray">@SpanTag(key = "test", resolver = TagValueResolver.class)</span></em> String test) {
|
|
}</pre><p>and such a <code class="literal">TagValueResolver</code> bean implementation</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean(name = "myCustomTagValueResolver")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> TagValueResolver tagValueResolver() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> parameter -> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Value from myCustomTagValueResolver"</span>;
|
|
}</pre><p>Will lead to setting of a tag value equal to <code class="literal">Value from myCustomTagValueResolver</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_resolving_expressions_for_value" href="#_resolving_expressions_for_value"></a>52.4.2 Resolving expressions for value</h3></div></div></div><p>Having such an annotated method:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> getAnnotationForTagValueExpression(<em><span class="hl-annotation" style="color: gray">@SpanTag(key = "test", expression = "length() + ' characters'")</span></em> String test) {
|
|
}</pre><p>and no custom implementation of a <code class="literal">TagValueExpressionResolver</code> will lead to evaluation of the SPEL expression and a tag with value <code class="literal">4 characters</code> will be set on the span.
|
|
If you want to use some other expression resolution mechanism you can create your own implementation
|
|
of the bean.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_using_tostring_method" href="#_using_tostring_method"></a>52.4.3 Using toString method</h3></div></div></div><p>Having such an annotated method:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@NewSpan</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> getAnnotationForArgumentToString(<em><span class="hl-annotation" style="color: gray">@SpanTag("test")</span></em> Long param) {
|
|
}</pre><p>if executed with a value of <code class="literal">15</code> will lead to setting of a tag with a String value of <code class="literal">"15"</code>.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_customizations" href="#_customizations"></a>53. Customizations</h2></div></div></div><p>Thanks to the <code class="literal">SpanInjector</code> and <code class="literal">SpanExtractor</code> you can customize the way spans
|
|
are created and propagated.</p><p>There are currently two built-in ways to pass tracing information between processes:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">via Spring Integration</li><li class="listitem">via HTTP</li></ul></div><p>Span ids are extracted from Zipkin-compatible (B3) headers (either <code class="literal">Message</code>
|
|
or HTTP headers), to start or join an existing trace. Trace information is
|
|
injected into any outbound requests so the next hop can extract them.</p><p>The key change in comparison to the previous versions of Sleuth is that Sleuth is implementing
|
|
the Open Tracing’s <code class="literal">TextMap</code> notion. In Sleuth it’s called <code class="literal">SpanTextMap</code>. Basically the idea
|
|
is that any means of communication (e.g. message, http request, etc.) can be abstracted via
|
|
a <code class="literal">SpanTextMap</code>. This abstraction defines how one can insert data into the carrier and
|
|
how to retrieve it from there. Thanks to this if you want to instrument a new HTTP library
|
|
that uses a <code class="literal">FooRequest</code> as a mean of sending HTTP requests then you have to create an
|
|
implementation of a <code class="literal">SpanTextMap</code> that delegates calls to <code class="literal">FooRequest</code> in terms of retrieval
|
|
and insertion of HTTP headers.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_spring_integration" href="#_spring_integration"></a>53.1 Spring Integration</h2></div></div></div><p>For Spring Integration there are 2 interfaces responsible for creation of a Span from a <code class="literal">Message</code>.
|
|
These are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">MessagingSpanTextMapExtractor</code></li><li class="listitem"><code class="literal">MessagingSpanTextMapInjector</code></li></ul></div><p>You can override them by providing your own implementation.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http" href="#_http"></a>53.2 HTTP</h2></div></div></div><p>For HTTP there are 2 interfaces responsible for creation of a Span from a <code class="literal">Message</code>.
|
|
These are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">HttpSpanExtractor</code></li><li class="listitem"><code class="literal">HttpSpanInjector</code></li></ul></div><p>You can override them by providing your own implementation.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_example" href="#_example"></a>53.3 Example</h2></div></div></div><p>Let’s assume that instead of the standard Zipkin compatible tracing HTTP header names
|
|
you have</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">for trace id - <code class="literal">correlationId</code></li><li class="listitem">for span id - <code class="literal">mySpanId</code></li></ul></div><p>This is a an example of a <code class="literal">SpanExtractor</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomHttpSpanExtractor <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> HttpSpanExtractor {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Span joinTrace(SpanTextMap carrier) {
|
|
Map<String, String> map = TextMapUtil.asMap(carrier);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">long</span> traceId = Span.hexToId(map.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"correlationid"</span>));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">long</span> spanId = Span.hexToId(map.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"myspanid"</span>));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// extract all necessary headers</span>
|
|
Span.SpanBuilder builder = Span.builder().traceId(traceId).spanId(spanId);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// build rest of the Span</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> builder.build();
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomHttpSpanInjector <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> HttpSpanInjector {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> inject(Span span, SpanTextMap carrier) {
|
|
carrier.put(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"correlationId"</span>, span.traceIdString());
|
|
carrier.put(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"mySpanId"</span>, Span.idToHex(span.getSpanId()));
|
|
}
|
|
}</pre><p>And you could register it like this:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
HttpSpanInjector customHttpSpanInjector() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CustomHttpSpanInjector();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
HttpSpanExtractor customHttpSpanExtractor() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CustomHttpSpanExtractor();
|
|
}</pre><p>Spring Cloud Sleuth does not add trace/span related headers to the Http Response for security reasons. If you need the headers then a custom <code class="literal">SpanInjector</code>
|
|
that injects the headers into the Http Response and a Servlet filter which makes use of this can be added the following way:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomHttpServletResponseSpanInjector <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> ZipkinHttpSpanInjector {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> inject(Span span, SpanTextMap carrier) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">super</span>.inject(span, carrier);
|
|
carrier.put(Span.TRACE_ID_NAME, span.traceIdString());
|
|
carrier.put(Span.SPAN_ID_NAME, Span.idToHex(span.getSpanId()));
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> HttpResponseInjectingTraceFilter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> GenericFilterBean {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Tracer tracer;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> HttpSpanInjector spanInjector;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> HttpResponseInjectingTraceFilter(Tracer tracer, HttpSpanInjector spanInjector) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer = tracer;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.spanInjector = spanInjector;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> doFilter(ServletRequest request, ServletResponse servletResponse, FilterChain filterChain) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> IOException, ServletException {
|
|
HttpServletResponse response = (HttpServletResponse) servletResponse;
|
|
Span currentSpan = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer.getCurrentSpan();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.spanInjector.inject(currentSpan, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpServletResponseTextMap(response));
|
|
filterChain.doFilter(request, response);
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> HttpServletResponseTextMap <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> SpanTextMap {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> HttpServletResponse delegate;
|
|
|
|
HttpServletResponseTextMap(HttpServletResponse delegate) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.delegate = delegate;
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Iterator<Map.Entry<String, String>> iterator() {
|
|
Map<String, String> map = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HashMap<>();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> (String header : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.delegate.getHeaderNames()) {
|
|
map.put(header, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.delegate.getHeader(header));
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> map.entrySet().iterator();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> put(String key, String value) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.delegate.addHeader(key, value);
|
|
}
|
|
}
|
|
}</pre><p>And you could register them like this:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em> HttpSpanInjector customHttpServletResponseSpanInjector() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CustomHttpServletResponseSpanInjector();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
HttpResponseInjectingTraceFilter responseInjectingTraceFilter(Tracer tracer) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpResponseInjectingTraceFilter(tracer, customHttpServletResponseSpanInjector());
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_tracefilter" href="#_tracefilter"></a>53.4 TraceFilter</h2></div></div></div><p>You can also modify the behaviour of the <code class="literal">TraceFilter</code> - the component that is responsible
|
|
for processing the input HTTP request and adding tags basing on the HTTP response. You can customize
|
|
the tags, or modify the response headers by registering your own instance of the <code class="literal">TraceFilter</code> bean.</p><p>In the following example we will register the <code class="literal">TraceFilter</code> bean and we will add the
|
|
<code class="literal">ZIPKIN-TRACE-ID</code> response header containing the current Span’s trace id. Also we will
|
|
add to the Span a tag with key <code class="literal">custom</code> and a value <code class="literal">tag</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
TraceFilter myTraceFilter(BeanFactory beanFactory, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Tracer tracer) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceFilter(beanFactory) {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> addResponseTags(HttpServletResponse response,
|
|
Throwable e) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// execute the default behaviour</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">super</span>.addResponseTags(response, e);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// for readability we're returning trace id in a hex form</span>
|
|
response.addHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"ZIPKIN-TRACE-ID"</span>,
|
|
Span.idToHex(tracer.getCurrentSpan().getTraceId()));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// we can also add some custom tags</span>
|
|
tracer.addTag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"custom"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"tag"</span>);
|
|
}
|
|
};
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_sa_tag_in_zipkin" href="#_custom_sa_tag_in_zipkin"></a>53.5 Custom SA tag in Zipkin</h2></div></div></div><p>Sometimes you want to create a manual Span that will wrap a call to an external service which is not instrumented.
|
|
What you can do is to create a span with the <code class="literal">peer.service</code> tag that will contain a value of the service that you want to call.
|
|
Below you can see an example of a call to Redis that is wrapped in such a span.</p><pre class="programlisting">org.springframework.cloud.sleuth.Span newSpan = tracer.createSpan(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"redis"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
newSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"redis.op"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"get"</span>);
|
|
newSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"lc"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"redis"</span>);
|
|
newSpan.logEvent(org.springframework.cloud.sleuth.Span.CLIENT_SEND);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// call redis service e.g</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// return (SomeObj) redisTemplate.opsForHash().get("MYHASH", someObjKey);</span>
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">finally</span> {
|
|
newSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"peer.service"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"redisService"</span>);
|
|
newSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"peer.ipv4"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"1.2.3.4"</span>);
|
|
newSpan.tag(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"peer.port"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"1234"</span>);
|
|
newSpan.logEvent(org.springframework.cloud.sleuth.Span.CLIENT_RECV);
|
|
tracer.close(newSpan);
|
|
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Remember not to add both <code class="literal">peer.service</code> tag and the <code class="literal">SA</code> tag! You have to add only <code class="literal">peer.service</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_service_name" href="#_custom_service_name"></a>53.6 Custom service name</h2></div></div></div><p>By default Sleuth assumes that when you send a span to Zipkin, you want the span’s service name
|
|
to be equal to <code class="literal">spring.application.name</code> value. That’s not always the case though. There
|
|
are situations in which you want to explicitly provide a different service name for all spans coming
|
|
from your application. To achieve that it’s enough to just pass the following property
|
|
to your application to override that value (example for <code class="literal">foo</code> service name):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.zipkin.service.name</span>: foo</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customization_of_reported_spans" href="#_customization_of_reported_spans"></a>53.7 Customization of reported spans</h2></div></div></div><p>Before reporting spans to e.g. Zipkin you can be interested in modifying that span in some way.
|
|
You can achieve that by using the <code class="literal">SpanAdjuster</code> interface.</p><p>Example of usage:</p><p>In Sleuth we’re generating spans with a fixed name. Some users want to modify the name depending on values
|
|
of tags. Implementation of the <code class="literal">SpanAdjuster</code> interface can be used to alter that name. Example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
SpanAdjuster customSpanAdjuster() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
return span -> span.toBuilder().name(scrub(span.getName())).build();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>This will lead in changing the name of the reported span just before it gets sent to Zipkin.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Your <code class="literal">SpanReporter</code> should inject the <code class="literal">SpanAdjuster</code> and
|
|
allow span manipulation before the actual reporting is done.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_host_locator" href="#_host_locator"></a>53.8 Host locator</h2></div></div></div><p>In order to define the host that is corresponding to a particular span we need to resolve the host name
|
|
and port. The default approach is to take it from server properties. If those for some reason are not set
|
|
then we’re trying to retrieve the host name from the network interfaces.</p><p>If you have the discovery client enabled and prefer to retrieve the host address from the registered
|
|
instance in a service registry then you have to set the property (it’s applicable for both HTTP and
|
|
Stream based span reporting).</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.zipkin.locator.discovery.enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_span_data_as_messages" href="#_span_data_as_messages"></a>54. Span Data as Messages</h2></div></div></div><p>You can accumulate and send span data over
|
|
<a class="link" href="http://cloud.spring.io/spring-cloud-stream" target="_top">Spring Cloud Stream</a> by
|
|
including the <code class="literal">spring-cloud-sleuth-stream</code> jar as a dependency, and
|
|
adding a Channel Binder implementation
|
|
(e.g. <code class="literal">spring-cloud-starter-stream-rabbit</code> for RabbitMQ or
|
|
<code class="literal">spring-cloud-starter-stream-kafka</code> for Kafka). This will
|
|
automatically turn your app into a producer of messages with payload
|
|
type <code class="literal">Spans</code>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_zipkin_consumer" href="#_zipkin_consumer"></a>54.1 Zipkin Consumer</h2></div></div></div><p>There is a special convenience annotation for setting up a message consumer
|
|
for the Span data and pushing it into a Zipkin <code class="literal">SpanStore</code>. This application</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableZipkinStreamServer</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Consumer {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(Consumer.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
}</pre><p>will listen for the Span data on whatever transport you provide via a
|
|
Spring Cloud Stream <code class="literal">Binder</code> (e.g. include
|
|
<code class="literal">spring-cloud-starter-stream-rabbit</code> for RabbitMQ, and similar
|
|
starters exist for Redis and Kafka). If you add the following UI dependency</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>io.zipkin.java<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>zipkin-autoconfigure-ui<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span></pre><p>Then you’ll have your app a
|
|
<a class="link" href="https://github.com/openzipkin/zipkin" target="_top">Zipkin server</a>, which hosts
|
|
the UI and api on port 9411.</p><p>The default <code class="literal">SpanStore</code> is in-memory (good for demos and getting
|
|
started quickly). For a more robust solution you can add MySQL and
|
|
<code class="literal">spring-boot-starter-jdbc</code> to your classpath and enable the JDBC
|
|
<code class="literal">SpanStore</code> via configuration, e.g.:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> rabbitmq</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> host</span>: ${RABBIT_HOST:localhost<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> datasource</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> schema</span>: classpath:/mysql.sql
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> url</span>: jdbc:mysql://${MYSQL_HOST:localhost}/test
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username</span>: root
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password</span>: root
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># Switch this on to create the schema on startup:</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> initialize</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> continueOnError</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> sleuth</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">zipkin</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> storage</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> type</span>: mysql</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">@EnableZipkinStreamServer</code> is also annotated with
|
|
<code class="literal">@EnableZipkinServer</code> so the process will also expose the standard
|
|
Zipkin server endpoints for collecting spans over HTTP, and for
|
|
querying in the Zipkin Web UI.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_consumer" href="#_custom_consumer"></a>54.2 Custom Consumer</h2></div></div></div><p>A custom consumer can also easily be implemented using
|
|
<code class="literal">spring-cloud-sleuth-stream</code> and binding to the <code class="literal">SleuthSink</code>. Example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableBinding(SleuthSink.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootApplication(exclude = SleuthStreamAutoConfiguration.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@MessageEndpoint</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Consumer {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@ServiceActivator(inputChannel = SleuthSink.INPUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> sink(Spans input) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// ... process spans</span>
|
|
}
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>the sample consumer application above explicitly excludes
|
|
<code class="literal">SleuthStreamAutoConfiguration</code> so it doesn’t send messages to itself,
|
|
but this is optional (you might actually want to trace requests into
|
|
the consumer app).</p></td></tr></table></div><p>In order to customize the polling mechanism you can create a bean of <code class="literal">PollerMetadata</code> type
|
|
with name equal to <code class="literal">StreamSpanReporter.POLLER</code>. Here you can find an example of such a configuration.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomPollerConfiguration {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean(name = StreamSpanReporter.POLLER)</span></em>
|
|
PollerMetadata customPoller() {
|
|
PollerMetadata poller = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> PollerMetadata();
|
|
poller.setMaxMessagesPerPoll(<span class="hl-number">500</span>);
|
|
poller.setTrigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> PeriodicTrigger(<span class="hl-number">5000L</span>));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> poller;
|
|
}
|
|
}</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_metrics" href="#_metrics"></a>55. Metrics</h2></div></div></div><p>Currently Spring Cloud Sleuth registers very simple metrics related to spans.
|
|
It’s using the <a class="link" href="http://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-metrics.html#production-ready-recording-metrics" target="_top">Spring Boot’s metrics support</a>
|
|
to calculate the number of accepted and dropped spans. Each time a span gets
|
|
sent to Zipkin the number of accepted spans will increase. If there’s an error then
|
|
the number of dropped spans will get increased.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_integrations" href="#_integrations"></a>56. Integrations</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_runnable_and_callable" href="#_runnable_and_callable"></a>56.1 Runnable and Callable</h2></div></div></div><p>If you’re wrapping your logic in <code class="literal">Runnable</code> or <code class="literal">Callable</code> it’s enough to wrap those classes in their Sleuth representative.</p><p>Example for <code class="literal">Runnable</code>:</p><pre class="programlisting">Runnable runnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Runnable() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> run() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// do some work</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String toString() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spanNameFromToStringMethod"</span>;
|
|
}
|
|
};
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Manual `TraceRunnable` creation with explicit "calculateTax" Span name</span>
|
|
Runnable traceRunnable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceRunnable(tracer, spanNamer, runnable, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Wrapping `Runnable` with `Tracer`. The Span name will be taken either from the</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `@SpanName` annotation or from `toString` method</span>
|
|
Runnable traceRunnableFromTracer = tracer.wrap(runnable);</pre><p>Example for <code class="literal">Callable</code>:</p><pre class="programlisting">Callable<String> callable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Callable<String>() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String call() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> someLogic();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String toString() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spanNameFromToStringMethod"</span>;
|
|
}
|
|
};
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Manual `TraceCallable` creation with explicit "calculateTax" Span name</span>
|
|
Callable<String> traceCallable = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceCallable<>(tracer, spanNamer, callable, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Wrapping `Callable` with `Tracer`. The Span name will be taken either from the</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `@SpanName` annotation or from `toString` method</span>
|
|
Callable<String> traceCallableFromTracer = tracer.wrap(callable);</pre><p>That way you will ensure that a new Span is created and closed for each execution.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_hystrix" href="#_hystrix"></a>56.2 Hystrix</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_custom_concurrency_strategy" href="#_custom_concurrency_strategy"></a>56.2.1 Custom Concurrency Strategy</h3></div></div></div><p>We’re registering a custom <a class="link" href="https://github.com/Netflix/Hystrix/wiki/Plugins#concurrencystrategy" target="_top"><code class="literal">HystrixConcurrencyStrategy</code></a>
|
|
that wraps all <code class="literal">Callable</code> instances into their Sleuth representative -
|
|
the <code class="literal">TraceCallable</code>. The strategy either starts or continues a span depending on the fact whether tracing was already going
|
|
on before the Hystrix command was called. To disable the custom Hystrix Concurrency Strategy set the <code class="literal">spring.sleuth.hystrix.strategy.enabled</code> to <code class="literal">false</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_manual_command_setting" href="#_manual_command_setting"></a>56.2.2 Manual Command setting</h3></div></div></div><p>Assuming that you have the following <code class="literal">HystrixCommand</code>:</p><pre class="programlisting">HystrixCommand<String> hystrixCommand = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HystrixCommand<String>(setter) {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> String run() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> someLogic();
|
|
}
|
|
};</pre><p>In order to pass the tracing information you have to wrap the same logic in the Sleuth version of the <code class="literal">HystrixCommand</code> which is the
|
|
<code class="literal">TraceCommand</code>:</p><pre class="programlisting">TraceCommand<String> traceCommand = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceCommand<String>(tracer, traceKeys, setter) {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String doRun() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> someLogic();
|
|
}
|
|
};</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_rxjava" href="#_rxjava"></a>56.3 RxJava</h2></div></div></div><p>We’re registering a custom <a class="link" href="https://github.com/ReactiveX/RxJava/wiki/Plugins#rxjavaschedulershook" target="_top"><code class="literal">RxJavaSchedulersHook</code></a>
|
|
that wraps all <code class="literal">Action0</code> instances into their Sleuth representative -
|
|
the <code class="literal">TraceAction</code>. The hook either starts or continues a span depending on the fact whether tracing was already going
|
|
on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the <code class="literal">spring.sleuth.rxjava.schedulers.hook.enabled</code> to <code class="literal">false</code>.</p><p>You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list
|
|
of regular expressions in the <code class="literal">spring.sleuth.rxjava.schedulers.ignoredthreads</code> property.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http_integration" href="#_http_integration"></a>56.4 HTTP integration</h2></div></div></div><p>Features from this section can be disabled by providing the <code class="literal">spring.sleuth.web.enabled</code> property with value equal to <code class="literal">false</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_http_filter" href="#_http_filter"></a>56.4.1 HTTP Filter</h3></div></div></div><p>Via the <code class="literal">TraceFilter</code> all sampled incoming requests result in creation of a Span. That Span’s name is <code class="literal">http:</code> + the path to which
|
|
the request was sent. E.g. if the request was sent to <code class="literal">/foo/bar</code> then the name will be <code class="literal">http:/foo/bar</code>. You can configure which URIs you would
|
|
like to skip via the <code class="literal">spring.sleuth.web.skipPattern</code> property. If you have <code class="literal">ManagementServerProperties</code> on classpath then
|
|
its value of <code class="literal">contextPath</code> gets appended to the provided skip pattern.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_handlerinterceptor" href="#_handlerinterceptor"></a>56.4.2 HandlerInterceptor</h3></div></div></div><p>Since we want the span names to be precise we’re using a <code class="literal">TraceHandlerInterceptor</code> that either wraps an
|
|
existing <code class="literal">HandlerInterceptor</code> or is added directly to the list of existing <code class="literal">HandlerInterceptors</code>. The
|
|
<code class="literal">TraceHandlerInterceptor</code> adds a special request attribute to the given <code class="literal">HttpServletRequest</code>. If the
|
|
the <code class="literal">TraceFilter</code> doesn’t see this attribute set it will create a "fallback" span which is an additional
|
|
span created on the server side so that the trace is presented properly in the UI. Seeing that most likely
|
|
signifies that there is a missing instrumentation. In that case please file an issue in Spring Cloud Sleuth.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_async_servlet_support" href="#_async_servlet_support"></a>56.4.3 Async Servlet support</h3></div></div></div><p>If your controller returns a <code class="literal">Callable</code> or a <code class="literal">WebAsyncTask</code> Spring Cloud Sleuth will continue the existing span instead of creating a new one.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http_client_integration" href="#_http_client_integration"></a>56.5 HTTP client integration</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_synchronous_rest_template" href="#_synchronous_rest_template"></a>56.5.1 Synchronous Rest Template</h3></div></div></div><p>We’re injecting a <code class="literal">RestTemplate</code> interceptor that ensures that all the tracing information is passed to the requests. Each time a
|
|
call is made a new Span is created. It gets closed upon receiving the response. In order to block the synchronous <code class="literal">RestTemplate</code> features
|
|
just set <code class="literal">spring.sleuth.web.client.enabled</code> to <code class="literal">false</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>You have to register <code class="literal">RestTemplate</code> as a bean so that the interceptors will get injected.
|
|
If you create a <code class="literal">RestTemplate</code> instance with a <code class="literal">new</code> keyword then the instrumentation WILL NOT work.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_asynchronous_rest_template" href="#_asynchronous_rest_template"></a>56.5.2 Asynchronous Rest Template</h3></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>A traced version of an <code class="literal">AsyncRestTemplate</code> bean is registered for you out of the box. If you
|
|
have your own bean you have to wrap it in a <code class="literal">TraceAsyncRestTemplate</code> representation. The best solution
|
|
is to only customize the <code class="literal">ClientHttpRequestFactory</code> and / or <code class="literal">AsyncClientHttpRequestFactory</code>.
|
|
<span class="strong"><strong>If you have your own <code class="literal">AsyncRestTemplate</code> and you don’t wrap it your calls WILL NOT GET TRACED</strong></span>.</p></td></tr></table></div><p>Custom instrumentation is set to create and close Spans upon sending and receiving requests. You can customize the <code class="literal">ClientHttpRequestFactory</code>
|
|
and the <code class="literal">AsyncClientHttpRequestFactory</code> by registering your beans. Remember to use tracing compatible implementations (e.g. don’t forget to
|
|
wrap <code class="literal">ThreadPoolTaskScheduler</code> in a <code class="literal">TraceAsyncListenableTaskExecutor</code>). Example of custom request factories:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> TestConfiguration {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
ClientHttpRequestFactory mySyncClientFactory() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MySyncClientHttpRequestFactory();
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
AsyncClientHttpRequestFactory myAsyncClientFactory() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> MyAsyncClientHttpRequestFactory();
|
|
}
|
|
}</pre><p>To block the <code class="literal">AsyncRestTemplate</code> features set <code class="literal">spring.sleuth.web.async.client.enabled</code> to <code class="literal">false</code>.
|
|
To disable creation of the default <code class="literal">TraceAsyncClientHttpRequestFactoryWrapper</code> set <code class="literal">spring.sleuth.web.async.client.factory.enabled</code>
|
|
to <code class="literal">false</code>. If you don’t want to create <code class="literal">AsyncRestClient</code> at all set <code class="literal">spring.sleuth.web.async.client.template.enabled</code> to <code class="literal">false</code>.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_multiple_asynchronous_rest_templates" href="#_multiple_asynchronous_rest_templates"></a>Multiple Asynchronous Rest Templates</h4></div></div></div><p>Sometimes you need to use multiple implementations of Asynchronous Rest Template. In the following snippet you
|
|
can see an example of how to set up such a custom <code class="literal">AsyncRestTemplate</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Config {
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> Tracer tracer;
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> HttpTraceKeysInjector httpTraceKeysInjector;
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> HttpSpanInjector spanInjector;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean(name = "customAsyncRestTemplate")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> AsyncRestTemplate traceAsyncRestTemplate(<em><span class="hl-annotation" style="color: gray">@Qualifier("customHttpRequestFactoryWrapper")</span></em>
|
|
TraceAsyncClientHttpRequestFactoryWrapper wrapper) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceAsyncRestTemplate(wrapper, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean(name = "customHttpRequestFactoryWrapper")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> TraceAsyncClientHttpRequestFactoryWrapper traceAsyncClientHttpRequestFactory() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceAsyncClientHttpRequestFactoryWrapper(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.tracer,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.spanInjector,
|
|
asyncClientFactory(),
|
|
clientHttpRequestFactory(),
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.httpTraceKeysInjector);
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> ClientHttpRequestFactory clientHttpRequestFactory() {
|
|
ClientHttpRequestFactory clientHttpRequestFactory = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CustomClientHttpRequestFactory();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//CUSTOMIZE HERE</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> clientHttpRequestFactory;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> AsyncClientHttpRequestFactory asyncClientFactory() {
|
|
AsyncClientHttpRequestFactory factory = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CustomAsyncClientHttpRequestFactory();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//CUSTOMIZE HERE</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> factory;
|
|
}
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_traverson" href="#_traverson"></a>56.5.3 Traverson</h3></div></div></div><p>If you’re using the <a class="link" href="http://docs.spring.io/spring-hateoas/docs/current/reference/html/#client.traverson" target="_top">Traverson</a> library
|
|
it’s enough for you to inject a <code class="literal">RestTemplate</code> as a bean into your Traverson object. Since <code class="literal">RestTemplate</code>
|
|
is already intercepted, you will get full support of tracing in your client. Below you can find a pseudo code
|
|
of how to do that:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Autowired</span></em> RestTemplate restTemplate;
|
|
|
|
Traverson traverson = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Traverson(URI.create(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://some/address"</span>),
|
|
MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// use Traverson</span></pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_feign" href="#_feign"></a>56.6 Feign</h2></div></div></div><p>By default Spring Cloud Sleuth provides integration with feign via the <code class="literal">TraceFeignClientAutoConfiguration</code>. You can disable it entirely
|
|
by setting <code class="literal">spring.sleuth.feign.enabled</code> to false. If you do so then no Feign related instrumentation will take place.</p><p>Part of Feign instrumentation is done via a <code class="literal">FeignBeanPostProcessor</code>. You can disable it by providing the <code class="literal">spring.sleuth.feign.processor.enabled</code> equal to <code class="literal">false</code>.
|
|
If you set it like this then Spring Cloud Sleuth will not instrument any of your custom Feign components. All the default instrumentation
|
|
however will be still there.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_asynchronous_communication" href="#_asynchronous_communication"></a>56.7 Asynchronous communication</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__async_annotated_methods" href="#__async_annotated_methods"></a>56.7.1 @Async annotated methods</h3></div></div></div><p>In Spring Cloud Sleuth we’re instrumenting async related components so that the tracing information is passed between threads.
|
|
You can disable this behaviour by setting the value of <code class="literal">spring.sleuth.async.enabled</code> to <code class="literal">false</code>.</p><p>If you annotate your method with <code class="literal">@Async</code> then we’ll automatically create a new Span with the following characteristics:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">the Span name will be the annotated method name</li><li class="listitem">the Span will be tagged with that method’s class name and the method name too</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="__scheduled_annotated_methods" href="#__scheduled_annotated_methods"></a>56.7.2 @Scheduled annotated methods</h3></div></div></div><p>In Spring Cloud Sleuth we’re instrumenting scheduled method execution so that the tracing information is passed between threads. You can disable this behaviour
|
|
by setting the value of <code class="literal">spring.sleuth.scheduled.enabled</code> to <code class="literal">false</code>.</p><p>If you annotate your method with <code class="literal">@Scheduled</code> then we’ll automatically create a new Span with the following characteristics:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">the Span name will be the annotated method name</li><li class="listitem">the Span will be tagged with that method’s class name and the method name too</li></ul></div><p>If you want to skip Span creation for some <code class="literal">@Scheduled</code> annotated classes you can set the
|
|
<code class="literal">spring.sleuth.scheduled.skipPattern</code> with a regular expression that will match the fully qualified name of the
|
|
<code class="literal">@Scheduled</code> annotated class.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>If you are using <code class="literal">spring-cloud-sleuth-stream</code> and <code class="literal">spring-cloud-netflix-hystrix-stream</code> together, Span will be created for each Hystrix metrics and sent to Zipkin. This may be annoying. You can prevent this by setting <code class="literal">spring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTask</code></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_executor_executorservice_and_scheduledexecutorservice" href="#_executor_executorservice_and_scheduledexecutorservice"></a>56.7.3 Executor, ExecutorService and ScheduledExecutorService</h3></div></div></div><p>We’re providing <code class="literal">LazyTraceExecutor</code>, <code class="literal">TraceableExecutorService</code> and <code class="literal">TraceableScheduledExecutorService</code>. Those implementations
|
|
are creating Spans each time a new task is submitted, invoked or scheduled.</p><p>Here you can see an example of how to pass tracing information with <code class="literal">TraceableExecutorService</code> when working with <code class="literal">CompletableFuture</code>:</p><pre class="programlisting">CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// perform some logic</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span class="hl-number">1</span>_<span class="hl-number">000</span>_<span class="hl-number">000L</span>;
|
|
}, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TraceableExecutorService(executorService,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// 'calculateTax' explicitly names the span - this param is optional</span>
|
|
tracer, traceKeys, spanNamer, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"calculateTax"</span>));</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_customization_of_executors" href="#_customization_of_executors"></a>Customization of Executors</h4></div></div></div><p>Sometimes you need to set up a custom instance of the <code class="literal">AsyncExecutor</code>. In the following snippet you
|
|
can see an example of how to set up such a custom <code class="literal">Executor</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAsync</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomExecutorConfig <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> AsyncConfigurerSupport {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> BeanFactory beanFactory;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Executor getAsyncExecutor() {
|
|
ThreadPoolTaskExecutor executor = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ThreadPoolTaskExecutor();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// CUSTOMIZE HERE</span>
|
|
executor.setCorePoolSize(<span class="hl-number">7</span>);
|
|
executor.setMaxPoolSize(<span class="hl-number">42</span>);
|
|
executor.setQueueCapacity(<span class="hl-number">11</span>);
|
|
executor.setThreadNamePrefix(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"MyExecutor-"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// DON'T FORGET TO INITIALIZE</span>
|
|
executor.initialize();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> LazyTraceExecutor(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.beanFactory, executor);
|
|
}
|
|
}</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_messaging" href="#_messaging"></a>56.8 Messaging</h2></div></div></div><p>Spring Cloud Sleuth integrates with <a class="link" href="http://projects.spring.io/spring-integration/" target="_top">Spring Integration</a>. It creates spans for publish and
|
|
subscribe events. To disable Spring Integration instrumentation, set <code class="literal">spring.sleuth.integration.enabled</code> to false.</p><p>You can provide the <code class="literal">spring.sleuth.integration.patterns</code> pattern to explicitly
|
|
provide the names of channels that you want to include for tracing. By default all channels
|
|
are included.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>When using the <code class="literal">Executor</code> to build a Spring Integration <code class="literal">IntegrationFlow</code> remember to use the <span class="strong"><strong>untraced</strong></span> version of the <code class="literal">Executor</code>.
|
|
Decorating Spring Integration Executor Channel with <code class="literal">TraceableExecutorService</code> will cause the spans to be improperly closed.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_zuul_2" href="#_zuul_2"></a>56.9 Zuul</h2></div></div></div><p>We’re registering Zuul filters to propagate the tracing information (the request header is enriched with tracing data).
|
|
To disable Zuul support set the <code class="literal">spring.sleuth.zuul.enabled</code> property to <code class="literal">false</code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_running_examples" href="#_running_examples"></a>57. Running examples</h2></div></div></div><p>You can find the running examples deployed in the <a class="link" href="https://run.pivotal.io/" target="_top">Pivotal Web Services</a>. Check them out in the following links:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://docssleuth-zipkin-server.cfapps.io/" target="_top">Zipkin for apps presented in the samples to the top</a></li><li class="listitem"><a class="link" href="http://docsbrewing-zipkin-web.cfapps.io/" target="_top">Zipkin for Brewery on PWS</a>, its <a class="link" href="https://github.com/spring-cloud-samples/brewery" target="_top">Github Code</a></li></ul></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_consul" href="#_spring_cloud_consul"></a>Part VIII. Spring Cloud Consul</h1></div></div></div><div class="partintro"><div></div><p><span class="strong"><strong>Dalston.SR4</strong></span></p><p>This project provides Consul integrations for Spring Boot apps through autoconfiguration
|
|
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
|
simple annotations you can quickly enable and configure the common patterns inside your
|
|
application and build large distributed systems with Consul based components. The
|
|
patterns provided include Service Discovery, Control Bus and Configuration.
|
|
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker
|
|
(Hystrix) are provided by integration with Spring Cloud Netflix.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-install" href="#spring-cloud-consul-install"></a>58. Install Consul</h2></div></div></div><p>Please see the <a class="link" href="https://www.consul.io/intro/getting-started/install.html" target="_top">installation documentation</a> for instructions on how to install Consul.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-agent" href="#spring-cloud-consul-agent"></a>59. Consul Agent</h2></div></div></div><p>A Consul Agent client must be available to all Spring Cloud Consul applications. By default, the Agent client is expected to be at <code class="literal">localhost:8500</code>. See the <a class="link" href="https://consul.io/docs/agent/basics.html" target="_top">Agent documentation</a> for specifics on how to start an Agent client and how to connect to a cluster of Consul Agent Servers. For development, after you have installed consul, you may start a Consul Agent using the following command:</p><pre class="screen">./src/main/bash/local_run_consul.sh</pre><p>This will start an agent in server mode on port 8500, with the ui available at <a class="link" href="http://localhost:8500" target="_top">http://localhost:8500</a></p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-discovery" href="#spring-cloud-consul-discovery"></a>60. Service Discovery with Consul</h2></div></div></div><p>Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. Consul provides Service Discovery services via an <a class="link" href="https://www.consul.io/docs/agent/http.html" target="_top">HTTP API</a> and <a class="link" href="https://www.consul.io/docs/agent/dns.html" target="_top">DNS</a>. Spring Cloud Consul leverages the HTTP API for service registration and discovery. This does not prevent non-Spring Cloud applications from leveraging the DNS interface. Consul Agents servers are run in a <a class="link" href="https://www.consul.io/docs/internals/architecture.html" target="_top">cluster</a> that communicates via a <a class="link" href="https://www.consul.io/docs/internals/gossip.html" target="_top">gossip protocol</a> and uses the <a class="link" href="https://www.consul.io/docs/internals/consensus.html" target="_top">Raft consensus protocol</a>.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate" href="#_how_to_activate"></a>60.1 How to activate</h2></div></div></div><p>To activate Consul Service Discovery use the starter with group <code class="literal">org.springframework.cloud</code> and artifact id <code class="literal">spring-cloud-starter-consul-discovery</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a> for details on setting up your build system with the current Spring Cloud Release Train.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_with_consul" href="#_registering_with_consul"></a>60.2 Registering with Consul</h2></div></div></div><p>When a client registers with Consul, it provides meta-data about itself such as host and port, id, name and tags. An HTTP <a class="link" href="https://www.consul.io/docs/agent/checks.html" target="_top">Check</a> is created by default that Consul hits the <code class="literal">/health</code> endpoint every 10 seconds. If the health check fails, the service instance is marked as critical.</p><p>Example Consul client:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableDiscoveryClient</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping("/")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String home() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello world"</span>;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SpringApplicationBuilder(Application.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).web(true).run(args);
|
|
}
|
|
|
|
}</pre><p>(i.e. utterly normal Spring Boot app). If the Consul client is located somewhere other than <code class="literal">localhost:8500</code>, the configuration is required to locate the client. Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
consul:
|
|
host: localhost
|
|
port: 8500</pre><p>
|
|
</p><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="images/caution.png"></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p>If you use <a class="link" href="#spring-cloud-consul-config" title="61. Distributed Configuration with Consul">Spring Cloud Consul Config</a>, the above values will need to be placed in <code class="literal">bootstrap.yml</code> instead of <code class="literal">application.yml</code>.</p></td></tr></table></div><p>The default service name, instance id and port, taken from the <code class="literal">Environment</code>, are <code class="literal">${spring.application.name}</code>, the Spring Context ID and <code class="literal">${server.port}</code> respectively.</p><p><code class="literal">@EnableDiscoveryClient</code> make the app into both a Consul "service" (i.e. it registers itself) and a "client" (i.e. it can query Consul to locate other services).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http_health_check" href="#_http_health_check"></a>60.3 HTTP Health Check</h2></div></div></div><p>The health check for a Consul instance defaults to "/health", which is the default locations of a useful endpoint in a Spring Boot Actuator application. You need to change these, even for an Actuator application if you use a non-default context path or servlet path (e.g. <code class="literal">server.servletPath=/foo</code>) or management endpoint path (e.g. <code class="literal">management.context-path=/admin</code>). The interval that Consul uses to check the health endpoint may also be configured. "10s" and "1m" represent 10 seconds and 1 minute respectively. Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
consul:
|
|
discovery:
|
|
healthCheckPath: ${management.context-path}/health
|
|
healthCheckInterval: 15s</pre><p>
|
|
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_metadata_and_consul_tags" href="#_metadata_and_consul_tags"></a>60.3.1 Metadata and Consul tags</h3></div></div></div><p>Consul does not yet support metadata on services. Spring Cloud’s <code class="literal">ServiceInstance</code> has a <code class="literal">Map<String, String> metadata</code> field. Spring Cloud Consul uses Consul tags to approximate metadata until Consul officially supports metadata. Tags with the form <code class="literal">key=value</code> will be split and used as a <code class="literal">Map</code> key and value respectively. Tags without the equal <code class="literal">=</code> sign, will be used as both the key and value.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
consul:
|
|
discovery:
|
|
tags: foo=bar, baz</pre><p>
|
|
</p><p>The above configuration will result in a map with <code class="literal">foo→bar</code> and <code class="literal">baz→baz</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_making_the_consul_instance_id_unique" href="#_making_the_consul_instance_id_unique"></a>60.3.2 Making the Consul Instance ID Unique</h3></div></div></div><p>By default a consul instance is registered with an ID that is equal to its Spring Application Context ID. By default, the Spring Application Context ID is <code class="literal">${spring.application.name}:comma,separated,profiles:${server.port}</code>. For most cases, this will allow multiple instances of one service to run on one machine. If further uniqueness is required, Using Spring Cloud you can override this by providing a unique identifier in <code class="literal">spring.cloud.consul.discovery.instanceId</code>. For example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
consul:
|
|
discovery:
|
|
instanceId: ${spring.application.name}:${vcap.application.instance_id:${spring.application.instance_id:${random.value}}}</pre><p>
|
|
</p><p>With this metadata, and multiple service instances deployed on localhost, the random value will kick in there to make the instance unique. In Cloudfoundry the <code class="literal">vcap.application.instance_id</code> will be populated automatically in a Spring Boot application, so the random value will not be needed.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_the_discoveryclient" href="#_using_the_discoveryclient"></a>60.4 Using the DiscoveryClient</h2></div></div></div><p>Spring Cloud has support for <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-feign" target="_top">Feign</a> (a REST client builder) and also <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-ribbon" target="_top">Spring <code class="literal">RestTemplate</code></a> using the logical service names instead of physical URLs.</p><p>You can also use the <code class="literal">org.springframework.cloud.client.discovery.DiscoveryClient</code> which provides a simple API for discovery clients that is not specific to Netflix, e.g.</p><pre class="screen">@Autowired
|
|
private DiscoveryClient discoveryClient;
|
|
|
|
public String serviceUrl() {
|
|
List<ServiceInstance> list = discoveryClient.getInstances("STORES");
|
|
if (list != null && list.size() > 0 ) {
|
|
return list.get(0).getUri();
|
|
}
|
|
return null;
|
|
}</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-config" href="#spring-cloud-consul-config"></a>61. Distributed Configuration with Consul</h2></div></div></div><p>Consul provides a <a class="link" href="https://consul.io/docs/agent/http/kv.html" target="_top">Key/Value Store</a> for storing configuration and other metadata. Spring Cloud Consul Config is an alternative to the <a class="link" href="https://github.com/spring-cloud/spring-cloud-config" target="_top">Config Server and Client</a>. Configuration is loaded into the Spring Environment during the special "bootstrap" phase. Configuration is stored in the <code class="literal">/config</code> folder by default. Multiple <code class="literal">PropertySource</code> instances are created based on the application’s name and the active profiles that mimicks the Spring Cloud Config order of resolving properties. For example, an application with the name "testApp" and with the "dev" profile will have the following property sources created:</p><pre class="screen">config/testApp,dev/
|
|
config/testApp/
|
|
config/application,dev/
|
|
config/application/</pre><p>The most specific property source is at the top, with the least specific at the bottom. Properties is the <code class="literal">config/application</code> folder are applicable to all applications using consul for configuration. Properties in the <code class="literal">config/testApp</code> folder are only available to the instances of the service named "testApp".</p><p>Configuration is currently read on startup of the application. Sending a HTTP POST to <code class="literal">/refresh</code> will cause the configuration to be reloaded. Watching the key value store (which Consul supports) is not currently possible, but will be a future addition to this project.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate_2" href="#_how_to_activate_2"></a>61.1 How to activate</h2></div></div></div><p>To get started with Consul Configuration use the starter with group <code class="literal">org.springframework.cloud</code> and artifact id <code class="literal">spring-cloud-starter-consul-config</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a> for details on setting up your build system with the current Spring Cloud Release Train.</p><p>This will enable auto-configuration that will setup Spring Cloud Consul Config.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customizing" href="#_customizing"></a>61.2 Customizing</h2></div></div></div><p>Consul Config may be customized using the following properties:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
consul:
|
|
config:
|
|
enabled: true
|
|
prefix: configuration
|
|
defaultContext: apps
|
|
profileSeparator: '::'</pre><p>
|
|
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to "false" disables Consul Config</li><li class="listitem"><code class="literal">prefix</code> sets the base folder for configuration values</li><li class="listitem"><code class="literal">defaultContext</code> sets the folder name used by all applications</li><li class="listitem"><code class="literal">profileSeparator</code> sets the value of the separator used to separate the profile name in property sources with profiles</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-consul-config-watch" href="#spring-cloud-consul-config-watch"></a>61.3 Config Watch</h2></div></div></div><p>The Consul Config Watch takes advantage of the ability of consul to <a class="link" href="https://www.consul.io/docs/agent/watches.html#keyprefix" target="_top">watch a key prefix</a>. The Config Watch makes a blocking Consul HTTP API call to determine if any relevant configuration data has changed for the current application. If there is new configuration data a Refresh Event is published. This is equivalent to calling the <code class="literal">/refresh</code> actuator endpoint.</p><p>To change the frequency of when the Config Watch is called change <code class="literal">spring.cloud.consul.config.watch.delay</code>. The default value is 1000, which is in milliseconds.</p><p>To disable the Config Watch set <code class="literal">spring.cloud.consul.config.watch.enabled=false</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-consul-config-format" href="#spring-cloud-consul-config-format"></a>61.4 YAML or Properties with Config</h2></div></div></div><p>It may be more convenient to store a blob of properties in YAML or Properties format as opposed to individual key/value pairs. Set the <code class="literal">spring.cloud.consul.config.format</code> property to <code class="literal">YAML</code> or <code class="literal">PROPERTIES</code>. For example to use YAML:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
consul:
|
|
config:
|
|
format: YAML</pre><p>
|
|
</p><p>YAML must be set in the appropriate <code class="literal">data</code> key in consul. Using the defaults above the keys would look like:</p><pre class="screen">config/testApp,dev/data
|
|
config/testApp/data
|
|
config/application,dev/data
|
|
config/application/data</pre><p>You could store a YAML document in any of the keys listed above.</p><p>You can change the data key using <code class="literal">spring.cloud.consul.config.data-key</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-consul-config-git2consul" href="#spring-cloud-consul-config-git2consul"></a>61.5 git2consul with Config</h2></div></div></div><p>git2consul is a Consul community project that loads files from a git repository to individual keys into Consul. By default the names of the keys are names of the files. YAML and Properties files are supported with file extensions of <code class="literal">.yml</code> and <code class="literal">.properties</code> respectively. Set the <code class="literal">spring.cloud.consul.config.format</code> property to <code class="literal">FILES</code>. For example:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
consul:
|
|
config:
|
|
format: FILES</pre><p>
|
|
</p><p>Given the following keys in <code class="literal">/config</code>, the <code class="literal">development</code> profile and an application name of <code class="literal">foo</code>:</p><pre class="screen">.gitignore
|
|
application.yml
|
|
bar.properties
|
|
foo-development.properties
|
|
foo-production.yml
|
|
foo.properties
|
|
master.ref</pre><p>the following property sources would be created:</p><pre class="screen">config/foo-development.properties
|
|
config/foo.properties
|
|
config/application.yml</pre><p>The value of each key needs to be a properly formatted YAML or Properties file.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="spring-cloud-consul-failfast" href="#spring-cloud-consul-failfast"></a>61.6 Fail Fast</h2></div></div></div><p>It may be convenient in certain circumstances (like local development or certain test scenarios) to not fail if consul isn’t available for configuration. Setting <code class="literal">spring.cloud.consul.config.failFast=false</code> in <code class="literal">bootstrap.yml</code> will cause the configuration module to log a warning rather than throw an exception. This will allow the application to continue startup normally.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-retry" href="#spring-cloud-consul-retry"></a>62. Consul Retry</h2></div></div></div><p>If you expect that the consul agent may occasionally be unavailable when
|
|
your app starts, you can ask it to keep trying after a failure. You need to add
|
|
<code class="literal">spring-retry</code> and <code class="literal">spring-boot-starter-aop</code> to your classpath. The default
|
|
behaviour is to retry 6 times with an initial backoff interval of 1000ms and an
|
|
exponential multiplier of 1.1 for subsequent backoffs. You can configure these
|
|
properties (and others) using <code class="literal">spring.cloud.consul.retry.*</code> configuration properties.
|
|
This works with both Spring Cloud Consul Config and Discovery registration.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>To take full control of the retry add a <code class="literal">@Bean</code> of type
|
|
<code class="literal">RetryOperationsInterceptor</code> with id "consulRetryInterceptor". Spring
|
|
Retry has a <code class="literal">RetryInterceptorBuilder</code> that makes it easy to create one.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-bus" href="#spring-cloud-consul-bus"></a>63. Spring Cloud Bus with Consul</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate_3" href="#_how_to_activate_3"></a>63.1 How to activate</h2></div></div></div><p>To get started with the Consul Bus use the starter with group <code class="literal">org.springframework.cloud</code> and artifact id <code class="literal">spring-cloud-starter-consul-bus</code>. See the <a class="link" href="http://projects.spring.io/spring-cloud/" target="_top">Spring Cloud Project page</a> for details on setting up your build system with the current Spring Cloud Release Train.</p><p>See the <a class="link" href="https://cloud.spring.io/spring-cloud-bus/" target="_top">Spring Cloud Bus</a> documentation for the available actuator endpoints and howto send custom messages.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-hystrix" href="#spring-cloud-consul-hystrix"></a>64. Circuit Breaker with Hystrix</h2></div></div></div><p>Applications can use the Hystrix Circuit Breaker provided by the Spring Cloud Netflix project by including this starter in the projects pom.xml: <code class="literal">spring-cloud-starter-hystrix</code>. Hystrix doesn’t depend on the Netflix Discovery Client. The <code class="literal">@EnableHystrix</code> annotation should be placed on a configuration class (usually the main class). Then methods can be annotated with <code class="literal">@HystrixCommand</code> to be protected by a circuit breaker. See <a class="link" href="http://projects.spring.io/spring-cloud/spring-cloud.html#_circuit_breaker_hystrix_clients" target="_top">the documentation</a> for more details.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-consul-turbine" href="#spring-cloud-consul-turbine"></a>65. Hystrix metrics aggregation with Turbine and Consul</h2></div></div></div><p>Turbine (provided by the Spring Cloud Netflix project), aggregates multiple instances Hystrix metrics streams, so the dashboard can display an aggregate view. Turbine uses the <code class="literal">DiscoveryClient</code> interface to lookup relevant instances. To use Turbine with Spring Cloud Consul, configure the Turbine application in a manner similar to the following examples:</p><p><b>pom.xml. </b>
|
|
</p><pre class="screen"><dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-netflix-turbine</artifactId>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-starter-consul-discovery</artifactId>
|
|
</dependency></pre><p>
|
|
</p><p>Notice that the Turbine dependency is not a starter. The turbine starter includes support for Netflix Eureka.</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring.application.name: turbine
|
|
applications: consulhystrixclient
|
|
turbine:
|
|
aggregator:
|
|
clusterConfig: ${applications}
|
|
appConfig: ${applications}</pre><p>
|
|
</p><p>The <code class="literal">clusterConfig</code> and <code class="literal">appConfig</code> sections must match, so it’s useful to put the comma-separated list of service ID’s into a separate configuration property.</p><p><b>Turbine.java. </b>
|
|
</p><pre class="screen">@EnableTurbine
|
|
@EnableDiscoveryClient
|
|
@SpringBootApplication
|
|
public class Turbine {
|
|
public static void main(String[] args) {
|
|
SpringApplication.run(DemoturbinecommonsApplication.class, args);
|
|
}
|
|
}</pre><p>
|
|
</p></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_zookeeper" href="#_spring_cloud_zookeeper"></a>Part IX. Spring Cloud Zookeeper</h1></div></div></div><div class="partintro"><div></div><p>This project provides Zookeeper integrations for Spring Boot apps through autoconfiguration
|
|
and binding to the Spring Environment and other Spring programming model idioms. With a few
|
|
simple annotations you can quickly enable and configure the common patterns inside your
|
|
application and build large distributed systems with Zookeeper based components. The
|
|
patterns provided include Service Discovery and Configuration.
|
|
Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon), Circuit Breaker
|
|
(Hystrix) are provided by integration with Spring Cloud Netflix.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-zookeeper-install" href="#spring-cloud-zookeeper-install"></a>66. Install Zookeeper</h2></div></div></div><p>Please see the <a class="link" href="http://zookeeper.apache.org/doc/current/zookeeperStarted.html" target="_top">installation documentation</a> for instructions on how to install Zookeeper.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-zookeeper-discovery" href="#spring-cloud-zookeeper-discovery"></a>67. Service Discovery with Zookeeper</h2></div></div></div><p>Service Discovery is one of the key tenets of a microservice based architecture. Trying to hand configure each client or some form of convention can be very difficult to do and can be very brittle. <a class="link" href="http://curator.apache.org" target="_top">Curator</a>(A java library for Zookeeper) provides Service Discovery services via <a class="link" href="http://curator.apache.org/curator-x-discovery/" target="_top">Service Discovery Extension</a>. Spring Cloud Zookeeper leverages this extension for service registration and discovery.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate_4" href="#_how_to_activate_4"></a>67.1 How to activate</h2></div></div></div><p>Including a dependency on <code class="literal">org.springframework.cloud:spring-cloud-starter-zookeeper-discovery</code> will enable auto-configuration that will setup Spring Cloud Zookeeper Discovery.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>You still need to include <code class="literal">org.springframework.boot:spring-boot-starter-web</code> for web functionality.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_with_zookeeper" href="#_registering_with_zookeeper"></a>67.2 Registering with Zookeeper</h2></div></div></div><p>When a client registers with Zookeeper, it provides meta-data about itself such as host and port, id and name.</p><p>Example Zookeeper client:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableDiscoveryClient</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping("/")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String home() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello world"</span>;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SpringApplicationBuilder(Application.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>).web(true).run(args);
|
|
}
|
|
|
|
}</pre><p>(i.e. utterly normal Spring Boot app). If Zookeeper is located somewhere other than <code class="literal">localhost:2181</code>, the configuration is required to locate the server. Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
zookeeper:
|
|
connect-string: localhost:2181</pre><p>
|
|
</p><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="images/caution.png"></td><th align="left">Caution</th></tr><tr><td align="left" valign="top"><p>If you use <a class="link" href="#spring-cloud-zookeeper-config" title="72. Distributed Configuration with Zookeeper">Spring Cloud Zookeeper Config</a>, the above values will need to be placed in <code class="literal">bootstrap.yml</code> instead of <code class="literal">application.yml</code>.</p></td></tr></table></div><p>The default service name, instance id and port, taken from the <code class="literal">Environment</code>, are <code class="literal">${spring.application.name}</code>, the Spring Context ID and <code class="literal">${server.port}</code> respectively.</p><p><code class="literal">@EnableDiscoveryClient</code> makes the app into both a Zookeeper "service" (i.e. it registers itself) and a "client" (i.e. it can query Zookeeper to locate other services).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_the_discoveryclient_2" href="#_using_the_discoveryclient_2"></a>67.3 Using the DiscoveryClient</h2></div></div></div><p>Spring Cloud has support for <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-feign" target="_top">Feign</a> (a REST client builder) and also <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-ribbon" target="_top">Spring <code class="literal">RestTemplate</code></a> using the logical service names instead of physical URLs.</p><p>You can also use the <code class="literal">org.springframework.cloud.client.discovery.DiscoveryClient</code> which provides a simple API for discovery clients that is not specific to Netflix, e.g.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> DiscoveryClient discoveryClient;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String serviceUrl() {
|
|
List<ServiceInstance> list = discoveryClient.getInstances(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"STORES"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (list != null && list.size() > <span class="hl-number">0</span> ) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> list.get(<span class="hl-number">0</span>).getUri().toString();
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> null;
|
|
}</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-zookeeper-netflix" href="#spring-cloud-zookeeper-netflix"></a>68. Using Spring Cloud Zookeeper with Spring Cloud Netflix Components</h2></div></div></div><p>Spring Cloud Netflix supplies useful tools that work regardless of which <code class="literal">DiscoveryClient</code> implementation is used. Feign, Turbine, Ribbon and Zuul all work with Spring Cloud Zookeeper.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_ribbon_with_zookeeper" href="#_ribbon_with_zookeeper"></a>68.1 Ribbon with Zookeeper</h2></div></div></div><p>Spring Cloud Zookeeper provides an implementation of Ribbon’s <code class="literal">ServerList</code>. When the <code class="literal">spring-cloud-starter-zookeeper-discovery</code> is used, Ribbon is auto-configured to use the <code class="literal">ZookeeperServerList</code> by default.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-zookeeper-service-registry" href="#spring-cloud-zookeeper-service-registry"></a>69. Spring Cloud Zookeeper and Service Registry</h2></div></div></div><p>Spring Cloud Zookeeper implements the <code class="literal">ServiceRegistry</code> interface allowing developers to register arbitrary service in a programmatic way.</p><p>The <code class="literal">ServiceInstanceRegistration</code> class offers a <code class="literal">builder()</code> method to create a <code class="literal">Registration</code> object that can be used by the <code class="literal">ServiceRegistry</code>.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> ZookeeperServiceRegistry serviceRegistry;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> registerThings() {
|
|
ZookeeperRegistration registration = ServiceInstanceRegistration.builder()
|
|
.defaultUriSpec()
|
|
.address(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"anyUrl"</span>)
|
|
.port(<span class="hl-number">10</span>)
|
|
.name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/a/b/c/d/anotherservice"</span>)
|
|
.build();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.serviceRegistry.register(registration);
|
|
}</pre><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_instance_status" href="#_instance_status"></a>69.1 Instance Status</h2></div></div></div><p>Netflix Eureka supports having instances registered with the server that are <code class="literal">OUT_OF_SERVICE</code> and not returned as active service instances. This is very useful for behaviors such as blue/green deployments. The Curator Service Discovery recipe does not support this behavior. Taking advantage of the flexible payload has let Spring Cloud Zookeeper implement <code class="literal">OUT_OF_SERVICE</code> by updating some specific metadata and then filtering on that metadata in the Ribbon <code class="literal">ZookeeperServerList</code>. The <code class="literal">ZookeeperServerList</code> filters out all non-null instance statuses that do not equal <code class="literal">UP</code>. If the instance status field is empty, it is considered <code class="literal">UP</code> for backwards compatibility. To change the status of an instance POST <code class="literal">OUT_OF_SERVICE</code> to the <code class="literal">ServiceRegistry</code> instance status actuator endpoint.</p><pre class="literallayout">----
|
|
$ echo -n OUT_OF_SERVICE | http POST http://localhost:8081/service-registry/instance-status
|
|
----</pre><pre class="literallayout">NOTE: The above example uses the `http` command from https://httpie.org</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-zookeeper-dependencies" href="#spring-cloud-zookeeper-dependencies"></a>70. Zookeeper Dependencies</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_the_zookeeper_dependencies" href="#_using_the_zookeeper_dependencies"></a>70.1 Using the Zookeeper Dependencies</h2></div></div></div><p>Spring Cloud Zookeeper gives you a possibility to provide dependencies of your application as properties. As dependencies you can understand other applications that are registered
|
|
in Zookeeper and which you would like to call via <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-feign" target="_top">Feign</a> (a REST client builder)
|
|
and also <a class="link" href="https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-ribbon" target="_top">Spring <code class="literal">RestTemplate</code></a>.</p><p>You can also benefit from the Zookeeper Dependency Watchers functionality that lets you control and monitor what is the state of your dependencies and decide what to do with that.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate_zookeeper_dependencies" href="#_how_to_activate_zookeeper_dependencies"></a>70.2 How to activate Zookeeper Dependencies</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Including a dependency on <code class="literal">org.springframework.cloud:spring-cloud-starter-zookeeper-discovery</code> will enable auto-configuration that will setup Spring Cloud Zookeeper Dependencies.</li><li class="listitem">If you have to have the <code class="literal">spring.cloud.zookeeper.dependencies</code> section properly set up - check the subsequent section for more details then the feature is active</li><li class="listitem">You can have the dependencies turned off even if you’ve provided the dependencies in your properties. Just set the property <code class="literal">spring.cloud.zookeeper.dependency.enabled</code> to false (defaults to <code class="literal">true</code>).</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_setting_up_zookeeper_dependencies" href="#_setting_up_zookeeper_dependencies"></a>70.3 Setting up Zookeeper Dependencies</h2></div></div></div><p>Let’s take a closer look at an example of dependencies representation:</p><p><b>application.yml. </b>
|
|
</p><pre class="screen">spring.application.name: yourServiceName
|
|
spring.cloud.zookeeper:
|
|
dependencies:
|
|
newsletter:
|
|
path: /path/where/newsletter/has/registered/in/zookeeper
|
|
loadBalancerType: ROUND_ROBIN
|
|
contentTypeTemplate: application/vnd.newsletter.$version+json
|
|
version: v1
|
|
headers:
|
|
header1:
|
|
- value1
|
|
header2:
|
|
- value2
|
|
required: false
|
|
stubs: org.springframework:foo:stubs
|
|
mailing:
|
|
path: /path/where/mailing/has/registered/in/zookeeper
|
|
loadBalancerType: ROUND_ROBIN
|
|
contentTypeTemplate: application/vnd.mailing.$version+json
|
|
version: v1
|
|
required: true</pre><p>
|
|
</p><p>Let’s now go through each part of the dependency one by one. The root property name is <code class="literal">spring.cloud.zookeeper.dependencies</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_aliases" href="#_aliases"></a>70.3.1 Aliases</h3></div></div></div><p>Below the root property you have to represent each dependency has by an alias due to the constraints of Ribbon (the application id has to be placed in the URL
|
|
thus you can’t pass any complex path like /foo/bar/name). The alias will be the name that you will use instead of serviceId for <code class="literal">DiscoveryClient</code>, <code class="literal">Feign</code> or <code class="literal">RestTemplate</code>.</p><p>In the aforementioned examples the aliases are <code class="literal">newsletter</code> and <code class="literal">mailing</code>. Example of Feign usage with <code class="literal">newsletter</code> would be:</p><pre class="screen">@FeignClient("newsletter")
|
|
public interface NewsletterService {
|
|
@RequestMapping(method = RequestMethod.GET, value = "/newsletter")
|
|
String getNewsletters();
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_path" href="#_path"></a>70.3.2 Path</h3></div></div></div><p>Represented by <code class="literal">path</code> yaml property.</p><p>Path is the path under which the dependency is registered under Zookeeper. Like presented before Ribbon operates on URLs thus this path is not compliant with its requirement.
|
|
That is why Spring Cloud Zookeeper maps the alias to the proper path.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_load_balancer_type" href="#_load_balancer_type"></a>70.3.3 Load balancer type</h3></div></div></div><p>Represented by <code class="literal">loadBalancerType</code> yaml property.</p><p>If you know what kind of load balancing strategy has to be applied when calling this particular dependency then you can provide it in the yaml file and it will be automatically applied.
|
|
You can choose one of the following load balancing strategies</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">STICKY - once chosen the instance will always be called</li><li class="listitem">RANDOM - picks an instance randomly</li><li class="listitem">ROUND_ROBIN - iterates over instances over and over again</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_content_type_template_and_version" href="#_content_type_template_and_version"></a>70.3.4 Content-Type template and version</h3></div></div></div><p>Represented by <code class="literal">contentTypeTemplate</code> and <code class="literal">version</code> yaml property.</p><p>If you version your api via the <code class="literal">Content-Type</code> header then you don’t want to add this header to each of your requests. Also if you want to call a new version of the API you don’t want to
|
|
roam around your code to bump up the API version. That’s why you can provide a <code class="literal">contentTypeTemplate</code> with a special <code class="literal">$version</code> placeholder. That placeholder will be filled by the value of the
|
|
<code class="literal">version</code> yaml property. Let’s take a look at an example.</p><p>Having the following <code class="literal">contentTypeTemplate</code>:</p><pre class="screen">application/vnd.newsletter.$version+json</pre><p>and the following <code class="literal">version</code>:</p><pre class="screen">v1</pre><p>Will result in setting up of a <code class="literal">Content-Type</code> header for each request:</p><pre class="screen">application/vnd.newsletter.v1+json</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_default_headers" href="#_default_headers"></a>70.3.5 Default headers</h3></div></div></div><p>Represented by <code class="literal">headers</code> map in yaml</p><p>Sometimes each call to a dependency requires setting up of some default headers. In order not to do that in code you can set them up in the yaml file.
|
|
Having the following <code class="literal">headers</code> section:</p><pre class="screen">headers:
|
|
Accept:
|
|
- text/html
|
|
- application/xhtml+xml
|
|
Cache-Control:
|
|
- no-cache</pre><p>Results in adding the <code class="literal">Accept</code> and <code class="literal">Cache-Control</code> headers with appropriate list of values in your HTTP request.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_obligatory_dependencies" href="#_obligatory_dependencies"></a>70.3.6 Obligatory dependencies</h3></div></div></div><p>Represented by <code class="literal">required</code> property in yaml</p><p>If one of your dependencies is required to be up and running when your application is booting then it’s enough to set up the <code class="literal">required: true</code> property in the yaml file.</p><p>If your application can’t localize the required dependency during boot time it will throw an exception and the Spring Context will fail to set up.
|
|
In other words your application won’t be able to start if the required dependency is not registered in Zookeeper.</p><p>You can read more about Spring Cloud Zookeeper Presence Checker in the following sections.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_stubs" href="#_stubs"></a>70.3.7 Stubs</h3></div></div></div><p>You can provide a colon separated path to the JAR containing stubs of the dependency. Example</p><pre class="screen">stubs: org.springframework:foo:stubs</pre><p>means that for a particular dependencies can be found under:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">groupId: <code class="literal">org.springframework</code></li><li class="listitem">artifactId: <code class="literal">foo</code></li><li class="listitem">classifier: <code class="literal">stubs</code> - this is the default value</li></ul></div><p>This is actually equal to</p><pre class="screen">stubs: org.springframework:foo</pre><p>since <code class="literal">stubs</code> is the default classifier.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_configuring_spring_cloud_zookeeper_dependencies" href="#_configuring_spring_cloud_zookeeper_dependencies"></a>70.4 Configuring Spring Cloud Zookeeper Dependencies</h2></div></div></div><p>There is a bunch of properties that you can set to enable / disable parts of Zookeeper Dependencies functionalities.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">spring.cloud.zookeeper.dependencies</code> - if you don’t set this property you won’t benefit from Zookeeper Dependencies</li><li class="listitem"><code class="literal">spring.cloud.zookeeper.dependency.ribbon.enabled</code> (enabled by default) - Ribbon requires explicit global configuration or a particular one for a dependency. By turning on this property
|
|
runtime load balancing strategy resolution is possible and you can profit from the <code class="literal">loadBalancerType</code> section of the Zookeeper Dependencies. The configuration that needs this property
|
|
has an implementation of <code class="literal">LoadBalancerClient</code> that delegates to the <code class="literal">ILoadBalancer</code> presented in the next bullet</li><li class="listitem"><code class="literal">spring.cloud.zookeeper.dependency.ribbon.loadbalancer</code> (enabled by default) - thanks to this property the custom <code class="literal">ILoadBalancer</code> knows that the part of the URI passed to Ribbon might
|
|
actually be the alias that has to be resolved to a proper path in Zookeeper. Without this property you won’t be able to register applications under nested paths.</li><li class="listitem"><code class="literal">spring.cloud.zookeeper.dependency.headers.enabled</code> (enabled by default) - this property registers such a <code class="literal">RibbonClient</code> that automatically will append appropriate headers and content
|
|
types with version as presented in the Dependency configuration. Without this setting of those two parameters will not be operational.</li><li class="listitem"><code class="literal">spring.cloud.zookeeper.dependency.resttemplate.enabled</code> (enabled by default) - when enabled will modify the request headers of <code class="literal">@LoadBalanced</code> annotated <code class="literal">RestTemplate</code> so that it passes
|
|
headers and content type with version set in Dependency configuration. Wihtout this setting of those two parameters will not be operational.</li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-zookeeper-dependency-watcher" href="#spring-cloud-zookeeper-dependency-watcher"></a>71. Spring Cloud Zookeeper Dependency Watcher</h2></div></div></div><p>The Dependency Watcher mechanism allows you to register listeners to your dependencies. The functionality is in fact an implementation of the <code class="literal">Observator</code> pattern. When a dependency changes
|
|
its state (UP or DOWN) then some custom logic can be applied.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate_5" href="#_how_to_activate_5"></a>71.1 How to activate</h2></div></div></div><p>Spring Cloud Zookeeper Dependencies functionality needs to be enabled to profit from Dependency Watcher mechanism.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_a_listener" href="#_registering_a_listener"></a>71.2 Registering a listener</h2></div></div></div><p>In order to register a listener you have to implement an interface <code class="literal">org.springframework.cloud.zookeeper.discovery.watcher.DependencyWatcherListener</code> and register it as a bean.
|
|
The interface gives you one method:</p><pre class="screen"> void stateChanged(String dependencyName, DependencyState newState);</pre><p>If you want to register a listener for a particular dependency then the <code class="literal">dependencyName</code> would be the discriminator for your concrete implementation. <code class="literal">newState</code> will provide you with information
|
|
whether your dependency has changed to <code class="literal">CONNECTED</code> or <code class="literal">DISCONNECTED</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_presence_checker" href="#_presence_checker"></a>71.3 Presence Checker</h2></div></div></div><p>Bound with Dependency Watcher is the functionality called Presence Checker. It allows you to provide custom behaviour upon booting of your application to react accordingly to the state
|
|
of your dependencies.</p><p>The default implementation of the abstract <code class="literal">org.springframework.cloud.zookeeper.discovery.watcher.presence.DependencyPresenceOnStartupVerifier</code> class is the
|
|
<code class="literal">org.springframework.cloud.zookeeper.discovery.watcher.presence.DefaultDependencyPresenceOnStartupVerifier</code> which works in the following way.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">If the dependency is marked us <code class="literal">required</code> and it’s not in Zookeeper then upon booting your application will throw an exception and shutdown</li><li class="listitem">If dependency is not <code class="literal">required</code> the <code class="literal">org.springframework.cloud.zookeeper.discovery.watcher.presence.LogMissingDependencyChecker</code> will log that application is missing at <code class="literal">WARN</code> level</li></ul></div><p>The functionality can be overriden since the <code class="literal">DefaultDependencyPresenceOnStartupVerifier</code> is registered only when there is no bean of <code class="literal">DependencyPresenceOnStartupVerifier</code>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="spring-cloud-zookeeper-config" href="#spring-cloud-zookeeper-config"></a>72. Distributed Configuration with Zookeeper</h2></div></div></div><p>Zookeeper provides a <a class="link" href="http://zookeeper.apache.org/doc/current/zookeeperOver.html#sc_dataModelNameSpace" target="_top">hierarchical namespace</a> that allows clients to store arbitrary data, such as configuration data. Spring Cloud Zookeeper Config is an alternative to the <a class="link" href="https://github.com/spring-cloud/spring-cloud-config" target="_top">Config Server and Client</a>. Configuration is loaded into the Spring Environment during the special "bootstrap" phase. Configuration is stored in the <code class="literal">/config</code> namespace by default. Multiple <code class="literal">PropertySource</code> instances are created based on the application’s name and the active profiles that mimicks the Spring Cloud Config order of resolving properties. For example, an application with the name "testApp" and with the "dev" profile will have the following property sources created:</p><pre class="screen">config/testApp,dev
|
|
config/testApp
|
|
config/application,dev
|
|
config/application</pre><p>The most specific property source is at the top, with the least specific at the bottom. Properties is the <code class="literal">config/application</code> namespace are applicable to all applications using zookeeper for configuration. Properties in the <code class="literal">config/testApp</code> namespace are only available to the instances of the service named "testApp".</p><p>Configuration is currently read on startup of the application. Sending a HTTP POST to <code class="literal">/refresh</code> will cause the configuration to be reloaded. Watching the configuration namespace (which Zookeeper supports) is not currently implemented, but will be a future addition to this project.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_activate_6" href="#_how_to_activate_6"></a>72.1 How to activate</h2></div></div></div><p>Including a dependency on <code class="literal">org.springframework.cloud:spring-cloud-starter-zookeeper-config</code> will enable auto-configuration that will setup Spring Cloud Zookeeper Config.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_customizing_2" href="#_customizing_2"></a>72.2 Customizing</h2></div></div></div><p>Zookeeper Config may be customized using the following properties:</p><p><b>bootstrap.yml. </b>
|
|
</p><pre class="screen">spring:
|
|
cloud:
|
|
zookeeper:
|
|
config:
|
|
enabled: true
|
|
root: configuration
|
|
defaultContext: apps
|
|
profileSeparator: '::'</pre><p>
|
|
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to "false" disables Zookeeper Config</li><li class="listitem"><code class="literal">root</code> sets the base namespace for configuration values</li><li class="listitem"><code class="literal">defaultContext</code> sets the name used by all applications</li><li class="listitem"><code class="literal">profileSeparator</code> sets the value of the separator used to separate the profile name in property sources with profiles</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_acls" href="#_acls"></a>72.3 ACLs</h2></div></div></div><p>You can add authentication information for Zookeeper ACLs by calling the addAuthInfo method of a
|
|
CuratorFramework bean. One way to accomplish this is by providing your own CuratorFramework bean:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@BoostrapConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomCuratorFrameworkConfig {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> CuratorFramework curatorFramework() {
|
|
CuratorFramework curator = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> CuratorFramework();
|
|
curator.addAuthInfo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"digest"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"user:password"</span>.getBytes());
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> curator;
|
|
}
|
|
|
|
}</pre><p>Consult <a class="link" href="https://github.com/spring-cloud/spring-cloud-zookeeper/blob/master/spring-cloud-zookeeper-core/src/main/java/org/springframework/cloud/zookeeper/ZookeeperAutoConfiguration.java" target="_top">the ZookeeperAutoConfiguration class</a>
|
|
to see how the CuratorFramework bean is configured by default.</p><p>Alternatively, you can add your credentials from a class that depends on the existing
|
|
CuratorFramework bean:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@BoostrapConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> DefaultCuratorFrameworkConfig {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> ZookeeperConfig(CuratorFramework curator) {
|
|
curator.addAuthInfo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"digest"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"user:password"</span>.getBytes());
|
|
}
|
|
|
|
}</pre><p>This must occur during the boostrapping phase. You can register configuration classes to run
|
|
during this phase by annotating them with <code class="literal">@BootstrapConfiguration</code> and including them in a
|
|
comma-separated list set as the value of the property
|
|
<code class="literal">org.springframework.cloud.bootstrap.BootstrapConfiguration</code> in the file
|
|
<code class="literal">resources/META-INF/spring.factories</code>:</p><p><b>resources/META-INF/spring.factories. </b>
|
|
</p><pre class="screen">org.springframework.cloud.bootstrap.BootstrapConfiguration=\
|
|
my.project.CustomCuratorFrameworkConfig,\
|
|
my.project.DefaultCuratorFrameworkConfig</pre><p>
|
|
</p><p>Unresolved directive in spring-cloud.adoc - include::../../../../cli/docs/src/main/asciidoc/spring-cloud-cli.adoc[]</p></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_security" href="#_spring_cloud_security"></a>Part X. Spring Cloud Security</h1></div></div></div><div class="partintro"><div></div><p>Spring Cloud Security offers a set of primitives for building secure
|
|
applications and services with minimum fuss. A declarative model which
|
|
can be heavily configured externally (or centrally) lends itself to
|
|
the implementation of large systems of co-operating, remote components,
|
|
usually with a central indentity management service. It is also extremely
|
|
easy to use in a service platform like Cloud Foundry. Building on
|
|
Spring Boot and Spring Security OAuth2 we can quickly create systems that
|
|
implement common patterns like single sign on, token relay and token
|
|
exchange.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at <a class="link" href="https://github.com/spring-cloud/spring-cloud-security/tree/master/src/main/asciidoc" target="_top">github</a>.</p></td></tr></table></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_quickstart" href="#_quickstart"></a>73. Quickstart</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_oauth2_single_sign_on" href="#_oauth2_single_sign_on"></a>73.1 OAuth2 Single Sign On</h2></div></div></div><p>Here’s a Spring Cloud "Hello World" app with HTTP Basic
|
|
authentication and a single user account:</p><p><b>app.groovy. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Grab('spring-boot-starter-security')</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Controller</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping('/')</span></em>
|
|
String home() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Hello World'</span>
|
|
}
|
|
|
|
}</pre><p>
|
|
</p><p>You can run it with <code class="literal">spring run app.groovy</code> and watch the logs for the password (username is "user"). So far this is just the default for a Spring Boot app.</p><p>Here’s a Spring Cloud app with OAuth2 SSO:</p><p><b>app.groovy. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Controller</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableOAuth2Sso</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping('/')</span></em>
|
|
String home() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Hello World'</span>
|
|
}
|
|
|
|
}</pre><p>
|
|
</p><p>Spot the difference? This app will actually behave exactly the same as
|
|
the previous one, because it doesn’t know it’s OAuth2 credentals
|
|
yet.</p><p>You can register an app in github quite easily, so try that if you
|
|
want a production app on your own domain. If you are happy to test on
|
|
localhost:8080, then set up these properties in your application
|
|
configuration:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">security</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> oauth2</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> client</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> clientId</span>: bd1c0a783ccdd1c9b9e4
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> clientSecret</span>: <span class="hl-number">1</span>a9030fbca47a5b2c28e92f19050bb77824b5ad1
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> accessTokenUri</span>: https://github.com/login/oauth/access_token
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> userAuthorizationUri</span>: https://github.com/login/oauth/authorize
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> clientAuthenticationScheme</span>: form
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> resource</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> userInfoUri</span>: https://api.github.com/user
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> preferTokenInfo</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span></pre><p>
|
|
</p><p>run the app above and it will redirect to github for authorization. If
|
|
you are already signed into github you won’t even notice that it has
|
|
authenticated. These credentials will only work if your app is
|
|
running on port 8080.</p><p>To limit the scope that the client asks for when it obtains an access token
|
|
you can set <code class="literal">security.oauth2.client.scope</code> (comma separated or an array in YAML). By
|
|
default the scope is empty and it is up to to Authorization Server to
|
|
decide what the defaults should be, usually depending on the settings in
|
|
the client registration that it holds.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The examples above are all Groovy scripts. If you want to write the
|
|
same code in Java (or Groovy) you need to add Spring Security OAuth2
|
|
to the classpath (e.g. see the
|
|
<a class="link" href="https://github.com/spring-cloud-samples/sso" target="_top">sample here</a>).</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_oauth2_protected_resource" href="#_oauth2_protected_resource"></a>73.2 OAuth2 Protected Resource</h2></div></div></div><p>You want to protect an API resource with an OAuth2 token? Here’s a
|
|
simple example (paired with the client above):</p><p><b>app.groovy. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Grab('spring-cloud-starter-security')</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableResourceServer</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping('/')</span></em>
|
|
def home() {
|
|
[message: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Hello World'</span>]
|
|
}
|
|
|
|
}</pre><p>
|
|
</p><p>and</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">security</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> oauth2</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> resource</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> userInfoUri</span>: https://api.github.com/user
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> preferTokenInfo</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span></pre><p>
|
|
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_more_detail" href="#_more_detail"></a>74. More Detail</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_single_sign_on" href="#_single_sign_on"></a>74.1 Single Sign On</h2></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>All of the OAuth2 SSO and resource server features moved to Spring Boot
|
|
in version 1.3. You can find documentation in the
|
|
<a class="link" href="http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/" target="_top">Spring Boot user guide</a>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_token_relay" href="#_token_relay"></a>74.2 Token Relay</h2></div></div></div><p>A Token Relay is where an OAuth2 consumer acts as a Client and
|
|
forwards the incoming token to outgoing resource requests. The
|
|
consumer can be a pure Client (like an SSO application) or a Resource
|
|
Server.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_client_token_relay" href="#_client_token_relay"></a>74.2.1 Client Token Relay</h3></div></div></div><p>If your app is a user facing OAuth2 client (i.e. has declared
|
|
<code class="literal">@EnableOAuth2Sso</code> or <code class="literal">@EnableOAuth2Client</code>) then it has an
|
|
<code class="literal">OAuth2ClientContext</code> in request scope from Spring Boot. You can
|
|
create your own <code class="literal">OAuth2RestTemplate</code> from this context and an
|
|
autowired <code class="literal">OAuth2ProtectedResourceDetails</code>, and then the context will
|
|
always forward the access token downstream, also refreshing the access
|
|
token automatically if it expires. (These are features of Spring
|
|
Security and Spring Boot.)</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Spring Boot (1.4.1) does not create an
|
|
<code class="literal">OAuth2ProtectedResourceDetails</code> automatically if you are using
|
|
<code class="literal">client_credentials</code> tokens. In that case you need to create your own
|
|
<code class="literal">ClientCredentialsResourceDetails</code> and configure it with
|
|
<code class="literal">@ConfigurationProperties("security.oauth2.client")</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_client_token_relay_in_zuul_proxy" href="#_client_token_relay_in_zuul_proxy"></a>74.2.2 Client Token Relay in Zuul Proxy</h3></div></div></div><p>If your app also has a
|
|
<a class="link" href="http://cloud.spring.io/spring-cloud.html#netflix-zuul-reverse-proxy" target="_top">Spring
|
|
Cloud Zuul</a> embedded reverse proxy (using <code class="literal">@EnableZuulProxy</code>) then you
|
|
can ask it to forward OAuth2 access tokens downstream to the services
|
|
it is proxying. Thus the SSO app above can be enhanced simply like
|
|
this:</p><p><b>app.groovy. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Controller</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableOAuth2Sso</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableZuulProxy</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
}</pre><p>
|
|
</p><p>and it will (in addition to logging the user in and grabbing a token)
|
|
pass the authentication token downstream to the <code class="literal">/proxy/*</code>
|
|
services. If those services are implemented with
|
|
<code class="literal">@EnableResourceServer</code> then they will get a valid token in the
|
|
correct header.</p><p>How does it work? The <code class="literal">@EnableOAuth2Sso</code> annotation pulls in
|
|
<code class="literal">spring-cloud-starter-security</code> (which you could do manually in a
|
|
traditional app), and that in turn triggers some autoconfiguration for
|
|
a <code class="literal">ZuulFilter</code>, which itself is activated because Zuul is on the
|
|
classpath (via <code class="literal">@EnableZuulProxy</code>). The
|
|
<a class="link" href="https://github.com/spring-cloud/spring-cloud-security/tree/master/src/main/java/org/springframework/cloud/security/oauth2/proxy/OAuth2TokenRelayFilter.java" target="_top">filter</a>
|
|
just extracts an access token from the currently authenticated user,
|
|
and puts it in a request header for the downstream requests.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_resource_server_token_relay" href="#_resource_server_token_relay"></a>74.2.3 Resource Server Token Relay</h3></div></div></div><p>If your app has <code class="literal">@EnableResourceServer</code> you might want to relay the
|
|
incoming token downstream to other services. If you use a
|
|
<code class="literal">RestTemplate</code> to contact the downstream services then this is just a
|
|
matter of how to create the template with the right context.</p><p>If your service uses <code class="literal">UserInfoTokenServices</code> to authenticate incoming
|
|
tokens (i.e. it is using the <code class="literal">security.oauth2.user-info-uri</code>
|
|
configuration), then you can simply create an <code class="literal">OAuth2RestTemplate</code>
|
|
using an autowired <code class="literal">OAuth2ClientContext</code> (it will be populated by the
|
|
authentication process before it hits the backend code). Equivalently
|
|
(with Spring Boot 1.4), you could inject a
|
|
<code class="literal">UserInfoRestTemplateFactory</code> and grab its <code class="literal">OAuth2RestTemplate</code> in
|
|
your configuration. For example:</p><p><b>MyConfiguration.java. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> OAuth2RestTemplate restTemplate(UserInfoRestTemplateFactory factory) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> factory.getUserInfoRestTemplate();
|
|
}</pre><p>
|
|
</p><p>This rest template will then have the same <code class="literal">OAuth2ClientContext</code>
|
|
(request-scoped) that is used by the authentication filter, so you can
|
|
use it to send requests with the same access token.</p><p>If your app is not using <code class="literal">UserInfoTokenServices</code> but is still a client
|
|
(i.e. it declares <code class="literal">@EnableOAuth2Client</code> or <code class="literal">@EnableOAuth2Sso</code>), then
|
|
with Spring Security Cloud any <code class="literal">OAuth2RestOperations</code> that the user
|
|
creates from an <code class="literal">@Autowired</code> <code class="literal">@OAuth2Context</code> will also forward
|
|
tokens. This feature is implemented by default as an MVC handler
|
|
interceptor, so it only works in Spring MVC. If you are not using MVC
|
|
you could use a custom filter or AOP interceptor wrapping an
|
|
<code class="literal">AccessTokenContextRelay</code> to provide the same feature.</p><p>Here’s a basic
|
|
example showing the use of an autowired rest template created
|
|
elsewhere ("foo.com" is a Resource Server accepting the same tokens as
|
|
the surrounding app):</p><p><b>MyController.java. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> OAuth2RestOperations restTemplate;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping("/relay")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String relay() {
|
|
ResponseEntity<String> response =
|
|
restTemplate.getForEntity(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"https://foo.com/bar"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Success! ("</span> + response.getBody() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">")"</span>;
|
|
}</pre><p>
|
|
</p><p>If you don’t want to forward tokens (and that is a valid
|
|
choice, since you might want to act as yourself, rather than the
|
|
client that sent you the token), then you only need to create your own
|
|
<code class="literal">OAuth2Context</code> instead of autowiring the default one.</p><p>Feign clients will also pick up an interceptor that uses the
|
|
<code class="literal">OAuth2ClientContext</code> if it is available, so they should also do a
|
|
token relay anywhere where a <code class="literal">RestTemplate</code> would.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_configuring_authentication_downstream_of_a_zuul_proxy" href="#_configuring_authentication_downstream_of_a_zuul_proxy"></a>75. Configuring Authentication Downstream of a Zuul Proxy</h2></div></div></div><p>You can control the authorization behaviour downstream of an
|
|
<code class="literal">@EnableZuulProxy</code> through the <code class="literal">proxy.auth.*</code> settings. Example:</p><p><b>application.yml. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">proxy</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> auth</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> customers</span>: oauth2
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> stores</span>: passthru
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> recommendations</span>: none</pre><p>
|
|
</p><p>In this example the "customers" service gets an OAuth2 token relay,
|
|
the "stores" service gets a passthrough (the authorization header is
|
|
just passed downstream), and the "recommendations" service has its
|
|
authorization header removed. The default behaviour is to do a token
|
|
relay if there is a token available, and passthru otherwise.</p><p>See
|
|
<a class="link" href="https://github.com/spring-cloud/spring-cloud-security/tree/master/src/main/java/org/springframework/cloud/security/oauth2/proxy/ProxyAuthenticationProperties" target="_top">
|
|
ProxyAuthenticationProperties</a> for full details.</p></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_for_cloud_foundry" href="#_spring_cloud_for_cloud_foundry"></a>Part XI. Spring Cloud for Cloud Foundry</h1></div></div></div><div class="partintro"><div></div><p>Spring Cloud for Cloudfoundry makes it easy to run
|
|
<a class="link" href="https://github.com/spring-cloud" target="_top">Spring Cloud</a> apps in
|
|
<a class="link" href="https://github.com/cloudfoundry" target="_top">Cloud Foundry</a> (the Platform as a
|
|
Service). Cloud Foundry has the notion of a "service", which is
|
|
middlware that you "bind" to an app, essentially providing it with an
|
|
environment variable containing credentials (e.g. the location and
|
|
username to use for the service).</p><p>The <code class="literal">spring-cloud-cloudfoundry-web</code> project provides basic support for
|
|
some enhanced features of webapps in Cloud Foundry: binding
|
|
automatically to single-sign-on services and optionally enabling
|
|
sticky routing for discovery.</p><p>The <code class="literal">spring-cloud-cloudfoundry-discovery</code> project provides an
|
|
implementation of Spring Cloud Commons <code class="literal">DiscoveryClient</code> so you can
|
|
<code class="literal">@EnableDiscoveryClient</code> and provide your credentials as
|
|
<code class="literal">spring.cloud.cloudfoundry.discovery.[email,password]</code> and then you
|
|
can use the <code class="literal">DiscoveryClient</code> directly or via a <code class="literal">LoadBalancerClient</code>
|
|
(also <code class="literal">*.url</code> if you are not connecting to
|
|
<a class="link" href="https://run.pivotal.io" target="_top">Pivotal Web Services</a>).</p><p>The first time you use it the discovery client might be slow owing to
|
|
the fact that it has to get an access token from Cloud Foundry.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_discovery" href="#_discovery"></a>76. Discovery</h2></div></div></div><p>Here’s a Spring Cloud app with Cloud Foundry discovery:</p><p><b>app.groovy. </b>
|
|
</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Grab('org.springframework.cloud:spring-cloud-cloudfoundry')</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableDiscoveryClient</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
DiscoveryClient client
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping('/')</span></em>
|
|
String home() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Hello from '</span> + client.getLocalServiceInstance()
|
|
}
|
|
|
|
}</pre><p>
|
|
</p><p>If you run it without any service bindings:</p><pre class="screen">$ spring jar app.jar app.groovy
|
|
$ cf push -p app.jar</pre><p>It will show its app name in the home page.</p><p>The <code class="literal">DiscoveryClient</code> can lists all the apps in a space, according to
|
|
the credentials it is authenticated with, where the space defaults to
|
|
the one the client is running in (if any). If neither org nor space
|
|
are configured, they default per the user’s profile in Cloud Foundry.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_single_sign_on_2" href="#_single_sign_on_2"></a>77. Single Sign On</h2></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>All of the OAuth2 SSO and resource server features moved to Spring Boot
|
|
in version 1.3. You can find documentation in the
|
|
<a class="link" href="http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/" target="_top">Spring Boot user guide</a>.</p></td></tr></table></div><p>This project provides automatic binding from CloudFoundry service
|
|
credentials to the Spring Boot features. If you have a CloudFoundry
|
|
service called "sso", for instance, with credentials containing
|
|
"client_id", "client_secret" and "auth_domain", it will bind
|
|
automatically to the Spring OAuth2 client that you enable with
|
|
<code class="literal">@EnableOAuth2Sso</code> (from Spring Boot). The name of the service can be
|
|
parameterized using <code class="literal">spring.oauth2.sso.serviceId</code>.</p></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_contract" href="#_spring_cloud_contract"></a>Part XII. Spring Cloud Contract</h1></div></div></div><div class="partintro"><div></div><p><span class="emphasis"><em>Documentation Authors: Adam Dudczak, Mathias Düsterhöft, Marcin Grzejszczak, Dennis Kieselhorst, Jakub Kubryński, Karol Lassak,
|
|
Olga Maciaszek-Sharma, Mariusz Smykuła, Dave Syer</em></span></p><p>Dalston.SR4</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_contract_2" href="#_spring_cloud_contract_2"></a>78. Spring Cloud Contract</h2></div></div></div><p>What you always need is confidence in pushing new features into a new application or service in a distributed system.
|
|
This project provides support for Consumer Driven Contracts and service schemas in Spring applications, covering a
|
|
range of options for writing tests, publishing them as assets, asserting that a contract is kept by producers
|
|
and consumers, for HTTP and message-based interactions.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_contract_verifier_introduction" href="#_spring_cloud_contract_verifier_introduction"></a>79. Spring Cloud Contract Verifier Introduction</h2></div></div></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>The Accurest project was initially started by Marcin Grzejszczak and Jakub Kubrynski (<a class="link" href="http://codearte.io" target="_top">codearte.io</a>)</p></td></tr></table></div><p>Just to make long story short - Spring Cloud Contract Verifier is a tool that enables Consumer Driven Contract (CDC) development of JVM-based applications. It is shipped
|
|
with <span class="emphasis"><em>Contract Definition Language</em></span> (DSL). Contract definitions are used to produce following resources:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">JSON stub definitions to be used by WireMock when doing integration testing on the client code (<span class="emphasis"><em>client tests</em></span>).
|
|
Test code must still be written by hand, test data is produced by Spring Cloud Contract Verifier.</li><li class="listitem">Messaging routes if you’re using one. We’re integrating with Spring Integration, Spring Cloud Stream, Spring AMQP and Apache Camel. You can however set your own integrations if you want to</li><li class="listitem">Acceptance tests (in JUnit or Spock) used to verify if server-side implementation of the API is compliant with the contract (<span class="emphasis"><em>server tests</em></span>).
|
|
Full test is generated by Spring Cloud Contract Verifier.</li></ul></div><p>Spring Cloud Contract Verifier moves TDD to the level of software architecture.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_why" href="#_why"></a>79.1 Why?</h2></div></div></div><p>Let us assume that we have a system comprising of multiple microservices:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/1.0.x/docs/src/main/asciidoc/images/Deps.png" alt="Microservices Architecture"></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_testing_issues" href="#_testing_issues"></a>79.1.1 Testing issues</h3></div></div></div><p>If we wanted to test the application in top left corner if it can communicate with other services then we could do one of two things:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">deploy all microservices and perform end to end tests</li><li class="listitem">mock other microservices in unit / integration tests</li></ul></div><p>Both have their advantages but also a lot of disadvantages. Let’s focus on the latter.</p><p><span class="strong"><strong>Deploy all microservices and perform end to end tests</strong></span></p><p>Advantages:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">simulates production</li><li class="listitem">tests real communication between services</li></ul></div><p>Disadvantages:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">to test one microservice we would have to deploy 6 microservices, a couple of databases etc.</li><li class="listitem">the environment where the tests would be conducted would be locked for a single suite of tests (i.e. nobody else would be able to run the tests in the meantime).</li><li class="listitem">long to run</li><li class="listitem">very late feedback</li><li class="listitem">extremely hard to debug</li></ul></div><p><span class="strong"><strong>Mock other microservices in unit / integration tests</strong></span></p><p>Advantages:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">very fast feedback</li><li class="listitem">no infrastructure requirements</li></ul></div><p>Disadvantages:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">the implementor of the service creates stubs thus they might have nothing to do with the reality</li><li class="listitem">you can go to production with passing tests and failing production</li></ul></div><p>To solve the aforementioned issues Spring Cloud Contract Verifier with Stub Runner were created. Their main idea is to give you very fast feedback, without the need
|
|
to set up the whole world of microservices. If you work on stubs then the only applications you need are those that your application is using directly.</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/1.0.x/docs/src/main/asciidoc/images/Stubs2.png" alt="Stubbed Services"></div></div><p>Spring Cloud Contract Verifier gives you the certainty that the stubs that you’re using were created by the service that you’re calling. Also if you can use them it means that they were
|
|
tested against the producer’s side. In other words - you can trust those stubs.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_purposes" href="#_purposes"></a>79.2 Purposes</h2></div></div></div><p>The main purposes of Spring Cloud Contract Verifier with Stub Runner are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">to ensure that WireMock / Messaging stubs (used when developing the client) are doing exactly what actual server-side implementation will do,</li><li class="listitem">to promote ATDD method and Microservices architectural style,</li><li class="listitem">to provide a way to publish changes in contracts that are immediately visible on both sides,</li><li class="listitem">to generate boilerplate test code used on the server side.</li></ul></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Spring Cloud Contract Verifier’s purpose is NOT to start writing business features in the contracts.
|
|
Let’s assume that we have a business use case of fraud check. If a user can be a fraud for 100 different reasons,
|
|
we would assume that you would create 2 contracts. One for the positive and one for the negative fraud case.
|
|
Contract tests are used to test contracts between applications and not to simulate full behaviour.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how" href="#_how"></a>79.3 How</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_define_the_contract" href="#_define_the_contract"></a>79.3.1 Define the contract</h3></div></div></div><p>As consumers we need to define what exactly we want to achieve. We need to formulate our expectations. That’s why we write the following contract.</p><p>Let’s assume that we’d like to send the request containing the id of the client and the amount he wants to borrow from us. We’d like to send it to the /fraudcheck url via the PUT method.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> contracts
|
|
|
|
org.springframework.cloud.contract.spec.Contract.make {
|
|
request { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (1)</span>
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'PUT'</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (2)</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/fraudcheck'</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (3)</span>
|
|
body([ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (4)</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"client.id"</span>: $(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[0-9]{10}'</span>)),
|
|
loanAmount: <span class="hl-number">99999</span>
|
|
])
|
|
headers { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (5)</span>
|
|
contentType(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>)
|
|
}
|
|
}
|
|
response { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (6)</span>
|
|
status <span class="hl-number">200</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (7)</span>
|
|
body([ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (8)</span>
|
|
fraudCheckStatus: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"FRAUD"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"rejection.reason"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Amount too high"</span>
|
|
])
|
|
headers { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (9)</span>
|
|
contentType(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>)
|
|
}
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">/*
|
|
From the Consumer perspective, when shooting a request in the integration test:
|
|
|
|
(1) - If the consumer sends a request
|
|
(2) - With the "PUT" method
|
|
(3) - to the URL "/fraudcheck"
|
|
(4) - with the JSON body that
|
|
* has a field `clientId` that matches a regular expression `[0-9]{10}`
|
|
* has a field `loanAmount` that is equal to `99999`
|
|
(5) - with header `Content-Type` equal to `application/json`
|
|
(6) - then the response will be sent with
|
|
(7) - status equal `200`
|
|
(8) - and JSON body equal to
|
|
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
|
|
(9) - with header `Content-Type` equal to `application/json`
|
|
|
|
From the Producer perspective, in the autogenerated producer-side test:
|
|
|
|
(1) - A request will be sent to the producer
|
|
(2) - With the "PUT" method
|
|
(3) - to the URL "/fraudcheck"
|
|
(4) - with the JSON body that
|
|
* has a field `clientId` that will have a generated value that matches a regular expression `[0-9]{10}`
|
|
* has a field `loanAmount` that is equal to `99999`
|
|
(5) - with header `Content-Type` equal to `application/json`
|
|
(6) - then the test will assert if the response has been sent with
|
|
(7) - status equal `200`
|
|
(8) - and JSON body equal to
|
|
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
|
|
(9) - with header `Content-Type` matching `application/json.*`
|
|
*/</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_client_side" href="#_client_side"></a>79.3.2 Client Side</h3></div></div></div><p>Spring Cloud Contract will generate stubs, which you can use during client side testing.
|
|
You will have a WireMock instance / Messaging route up and running that simulates the service Y.
|
|
You would like to feed that instance with a proper stub definition.</p><p>At some point in time you need to send a request to the Fraud Detection service.</p><pre class="programlisting">ResponseEntity<FraudServiceResponse> response =
|
|
restTemplate.exchange(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://localhost:"</span> + port + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/fraudcheck"</span>, HttpMethod.PUT,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpEntity<>(request, httpHeaders),
|
|
FraudServiceResponse.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);</pre><p>Annotate your test class with <code class="literal">@AutoConfigureStubRunner</code>. In the annotation provide the group id and artifact id for the Stub Runner to download stubs of your collaborators.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(webEnvironment=WebEnvironment.NONE)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"}, workOffline = true)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@DirtiesContext</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> LoanApplicationServiceTests {</pre><p>After that, during the tests Spring Cloud Contract will automatically find the stubs (simulating the real service) in Maven repository and expose them on configured (or random) port.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_server_side" href="#_server_side"></a>79.3.3 Server Side</h3></div></div></div><p>Being a service Y since you are developing your stub, you need to be sure that it’s actually resembling your
|
|
concrete implementation. You can’t have a situation where your stub acts in one way and your application on
|
|
production behaves in a different way.</p><p>That’s why from the provided stub acceptance tests will be generated that will ensure
|
|
that your application behaves in the same way as you define in your stub.</p><p>The autogenerated test would look like this:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> validate_shouldMarkClientAsFraud() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json"</span>)
|
|
.body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"client.id\":\"1234567890\",\"loanAmount\":99999}"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.put(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/fraudcheck"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);
|
|
assertThat(response.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1.json.*"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['fraudCheckStatus']"</span>).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[A-Z]{5}"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['rejection.reason']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Amount too high"</span>);
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_step_by_step_guide_to_cdc" href="#_step_by_step_guide_to_cdc"></a>79.4 Step by step guide to CDC</h2></div></div></div><p>Let’s take an example of Fraud Detection and Loan Issuance process. The business scenario is such that we want to issue loans to people but don’t want them to steal the money from us. The current implementation of our system grants loans to everybody.</p><p>Let’s assume that the <code class="literal">Loan Issuance</code> is a client to the
|
|
<code class="literal">Fraud Detection</code> server. In the current sprint we are required to develop a new feature - if a client wants to borrow too much money then we mark him as fraud.</p><p>Technical remark - Fraud Detection will have artifact id <code class="literal">http-server</code>, Loan Issuance <code class="literal">http-client</code> and both have group id <code class="literal">com.example</code>.</p><p>Social remark - both client and server development teams need to communicate directly and discuss changes while
|
|
going through the process. CDC is all about communication.</p><p>The <a class="link" href="https://github.com/spring-cloud/spring-cloud-contract/tree/1.0.x/samples/standalone/dsl/http-server" target="_top">server side code is available here</a> and <a class="link" href="https://github.com/spring-cloud/spring-cloud-contract/tree/1.0.x/samples/standalone/dsl/http-client" target="_top">the client side code here</a>.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>In this case the ownership of the contracts lays on the producer side. It means that physically
|
|
all the contract are present in the producer’s repository</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_technical_note" href="#_technical_note"></a>79.4.1 Technical note</h3></div></div></div><p>If using the <span class="strong"><strong>SNAPSHOT</strong></span> / <span class="strong"><strong>Milestone</strong></span> / <span class="strong"><strong>Release Candidate</strong></span> versions please add the following section to your</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/snapshot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/milestone<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/release<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/snapshot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/milestone<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/release<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepositories></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">repositories {
|
|
mavenCentral()
|
|
mavenLocal()
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/snapshot"</span> }
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/milestone"</span> }
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/release"</span> }
|
|
}</pre><p class="secondary">
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_consumer_side_loan_issuance" href="#_consumer_side_loan_issuance"></a>79.4.2 Consumer side (Loan Issuance)</h3></div></div></div><p>As a developer of the Loan Issuance service (a consumer of the Fraud Detection server):</p><p><span class="strong"><strong>start doing TDD by writing a test to your feature</strong></span></p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> shouldBeRejectedDueToAbnormalLoanAmount() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
LoanApplication application = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> LoanApplication(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Client(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"1234567890"</span>),
|
|
<span class="hl-number">99999</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
LoanApplicationResult loanApplication = service.loanApplication(application);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(loanApplication.getLoanApplicationStatus())
|
|
.isEqualTo(LoanApplicationStatus.LOAN_APPLICATION_REJECTED);
|
|
assertThat(loanApplication.getRejectionReason()).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Amount too high"</span>);
|
|
}</pre><p>We’ve just written a test of our new feature. If a loan application for a big amount is received we should reject that loan application with some description.</p><p><span class="strong"><strong>write the missing implementation</strong></span></p><p>At some point in time you need to send a request to the Fraud Detection service. Let’s assume that we’d like to send the request containing the id of the client and the amount he wants to borrow from us. We’d like to send it to the <code class="literal">/fraudcheck</code> url via the <code class="literal">PUT</code> method.</p><pre class="programlisting">ResponseEntity<FraudServiceResponse> response =
|
|
restTemplate.exchange(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://localhost:"</span> + port + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/fraudcheck"</span>, HttpMethod.PUT,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpEntity<>(request, httpHeaders),
|
|
FraudServiceResponse.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);</pre><p>For simplicity we’ve hardcoded the port of the Fraud Detection service at <code class="literal">8080</code> and our application is running on <code class="literal">8090</code>.</p><p>If we’d start the written test it would obviously break since we have no service running on port <code class="literal">8080</code>.</p><p><span class="strong"><strong>clone the Fraud Detection service repository locally</strong></span></p><p>We’ll start playing around with the server side contract. That’s why we need to first clone it.</p><pre class="programlisting">git clone https://your-git-server.com/server-side.git local-http-server-repo</pre><p><span class="strong"><strong>define the contract locally in the repo of Fraud Detection service</strong></span></p><p>As consumers we need to define what exactly we want to achieve. We need to formulate our expectations. That’s why we write the following contract.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>We’re placing the contract under <code class="literal">src/test/resources/contracts/fraud</code> folder. The <code class="literal">fraud</code> folder
|
|
is important cause we’ll reference that folder in the producer’s test base class name.</p></td></tr></table></div><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> contracts
|
|
|
|
org.springframework.cloud.contract.spec.Contract.make {
|
|
request { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (1)</span>
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'PUT'</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (2)</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/fraudcheck'</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (3)</span>
|
|
body([ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (4)</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"client.id"</span>: $(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[0-9]{10}'</span>)),
|
|
loanAmount: <span class="hl-number">99999</span>
|
|
])
|
|
headers { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (5)</span>
|
|
contentType(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>)
|
|
}
|
|
}
|
|
response { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (6)</span>
|
|
status <span class="hl-number">200</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (7)</span>
|
|
body([ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (8)</span>
|
|
fraudCheckStatus: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"FRAUD"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"rejection.reason"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Amount too high"</span>
|
|
])
|
|
headers { <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (9)</span>
|
|
contentType(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>)
|
|
}
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">/*
|
|
From the Consumer perspective, when shooting a request in the integration test:
|
|
|
|
(1) - If the consumer sends a request
|
|
(2) - With the "PUT" method
|
|
(3) - to the URL "/fraudcheck"
|
|
(4) - with the JSON body that
|
|
* has a field `clientId` that matches a regular expression `[0-9]{10}`
|
|
* has a field `loanAmount` that is equal to `99999`
|
|
(5) - with header `Content-Type` equal to `application/json`
|
|
(6) - then the response will be sent with
|
|
(7) - status equal `200`
|
|
(8) - and JSON body equal to
|
|
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
|
|
(9) - with header `Content-Type` equal to `application/json`
|
|
|
|
From the Producer perspective, in the autogenerated producer-side test:
|
|
|
|
(1) - A request will be sent to the producer
|
|
(2) - With the "PUT" method
|
|
(3) - to the URL "/fraudcheck"
|
|
(4) - with the JSON body that
|
|
* has a field `clientId` that will have a generated value that matches a regular expression `[0-9]{10}`
|
|
* has a field `loanAmount` that is equal to `99999`
|
|
(5) - with header `Content-Type` equal to `application/json`
|
|
(6) - then the test will assert if the response has been sent with
|
|
(7) - status equal `200`
|
|
(8) - and JSON body equal to
|
|
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
|
|
(9) - with header `Content-Type` matching `application/json.*`
|
|
*/</span></pre><p>The Contract is written using a statically typed Groovy DSL. You might be wondering what are those
|
|
<code class="literal">value(client(…​), server(…​))</code> parts. By using this notation Spring Cloud Contract allows you to
|
|
define parts of a JSON / URL / etc. which are dynamic. In case of an identifier or a timestamp you
|
|
don’t want to hardcode a value. You want to allow some different ranges of values. That’s why for
|
|
the consumer side you can set regular expressions matching those values. You can provide the body
|
|
either by means of a map notation or String with interpolations.
|
|
<a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_contract_dsl" target="_top">Consult the docs
|
|
for more information.</a> We highly recommend using the map notation!</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>It’s really important that you understand the map notation to set up contracts. Please read the
|
|
<a class="link" href="http://groovy-lang.org/json.html" target="_top">Groovy docs regarding JSON</a></p></td></tr></table></div><p>The aforementioned contract is an agreement between two sides that:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p class="simpara">if an HTTP request is sent with</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">a method <code class="literal">PUT</code> on an endpoint <code class="literal">/fraudcheck</code></li><li class="listitem">JSON body with <code class="literal">client.id</code> matching the regular expression <code class="literal">[0-9]{10}</code> and <code class="literal">loanAmount</code> equal to <code class="literal">99999</code></li><li class="listitem">and with a header <code class="literal">Content-Type</code> equal to <code class="literal">application/vnd.fraud.v1+json</code></li></ul></div></li><li class="listitem"><p class="simpara">then an HTTP response would be sent to the consumer that</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">has status <code class="literal">200</code></li><li class="listitem">contains JSON body with the <code class="literal">fraudCheckStatus</code> field containing a value <code class="literal">FRAUD</code> and the <code class="literal">rejectionReason</code> field having value <code class="literal">Amount too high</code></li><li class="listitem">and a <code class="literal">Content-Type</code> header with a value of <code class="literal">application/vnd.fraud.v1+json</code></li></ul></div></li></ul></div><p>Once we’re ready to check the API in practice in the integration tests we need to just install the stubs locally</p><p><span class="strong"><strong>add the Spring Cloud Contract Verifier plugin</strong></span></p><p>We can add either Maven or Gradle plugin - in this example we’ll show how to add Maven. First we need to add the <code class="literal">Spring Cloud Contract</code> BOM.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-dependencies.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span></pre><p>Next, the <code class="literal">Spring Cloud Contract Verifier</code> Maven plugin</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><extensions></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></extensions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>com.example.fraud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>Since the plugin was added we get the <code class="literal">Spring Cloud Contract Verifier</code> features which from the provided contracts:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">generate and run tests</li><li class="listitem">produce and install stubs</li></ul></div><p>We don’t want to generate tests since we, as consumers, want only to play with the stubs. That’s why we need to skip the tests generation and execution. When we execute:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">cd</span> local-http-server-repo
|
|
./mvnw clean install -DskipTests</pre><p>In the logs we’ll see something like this:</p><pre class="programlisting">[INFO] --- spring-cloud-contract-maven-plugin:<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>BUILD-SNAPSHOT:generateStubs (default-generateStubs) @ http-server ---
|
|
[INFO] Building jar: /some/path/http-server/target/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar
|
|
[INFO]
|
|
[INFO] --- maven-jar-plugin:<span class="hl-number">2.6</span>:jar (default-jar) @ http-server ---
|
|
[INFO] Building jar: /some/path/http-server/target/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT.jar
|
|
[INFO]
|
|
[INFO] --- spring-boot-maven-plugin:<span class="hl-number">1.5</span>.<span class="hl-number">4.</span>BUILD-SNAPSHOT:repackage (default) @ http-server ---
|
|
[INFO]
|
|
[INFO] --- maven-install-plugin:<span class="hl-number">2.5</span>.<span class="hl-number">2</span>:install (default-install) @ http-server ---
|
|
[INFO] Installing /some/path/http-server/target/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT.jar to /path/to/your/.m2/repository/com/example/http-server/<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT.jar
|
|
[INFO] Installing /some/path/http-server/pom.xml to /path/to/your/.m2/repository/com/example/http-server/<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT.pom
|
|
[INFO] Installing /some/path/http-server/target/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar</pre><p>This line is extremely important</p><pre class="programlisting">[INFO] Installing /some/path/http-server/target/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar</pre><p>It’s confirming that the stubs of the <code class="literal">http-server</code> have been installed in the local repository.</p><p><span class="strong"><strong>run the integration tests</strong></span></p><p>In order to profit from the Spring Cloud Contract Stub Runner functionality of automatic stub downloading you have to do the following in our consumer side project (<code class="literal">Loan Application service</code>).</p><p>Add the <code class="literal">Spring Cloud Contract</code> BOM</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-dependencies.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span></pre><p>Add the dependency to <code class="literal">Spring Cloud Contract Stub Runner</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-contract-stub-runner<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>Annotate your test class with <code class="literal">@AutoConfigureStubRunner</code>. In the annotation provide the group id and artifact id for the Stub Runner to download stubs of your collaborators. Also provide the offline work switch since you’re playing with the collaborators offline (optional step).</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(webEnvironment=WebEnvironment.NONE)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"}, workOffline = true)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@DirtiesContext</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> LoanApplicationServiceTests {</pre><p>Now if you run your tests you’ll see sth like this:</p><pre class="programlisting"><span class="hl-number">2016</span>-<span class="hl-number">07</span>-<span class="hl-number">19</span> <span class="hl-number">14</span>:<span class="hl-number">22</span>:<span class="hl-number">25.403</span> INFO <span class="hl-number">41050</span> --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is + - will try to resolve the latest version
|
|
<span class="hl-number">2016</span>-<span class="hl-number">07</span>-<span class="hl-number">19</span> <span class="hl-number">14</span>:<span class="hl-number">22</span>:<span class="hl-number">25.438</span> INFO <span class="hl-number">41050</span> --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is <span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT
|
|
<span class="hl-number">2016</span>-<span class="hl-number">07</span>-<span class="hl-number">19</span> <span class="hl-number">14</span>:<span class="hl-number">22</span>:<span class="hl-number">25.439</span> INFO <span class="hl-number">41050</span> --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolving artifact com.example:http-server:jar:stubs:<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT using remote repositories []
|
|
<span class="hl-number">2016</span>-<span class="hl-number">07</span>-<span class="hl-number">19</span> <span class="hl-number">14</span>:<span class="hl-number">22</span>:<span class="hl-number">25.451</span> INFO <span class="hl-number">41050</span> --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact com.example:http-server:jar:stubs:<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT to /path/to/your/.m2/repository/com/example/http-server/<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar
|
|
<span class="hl-number">2016</span>-<span class="hl-number">07</span>-<span class="hl-number">19</span> <span class="hl-number">14</span>:<span class="hl-number">22</span>:<span class="hl-number">25.465</span> INFO <span class="hl-number">41050</span> --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/path/to/your/.m2/repository/com/example/http-server/<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT/http-server-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar]
|
|
<span class="hl-number">2016</span>-<span class="hl-number">07</span>-<span class="hl-number">19</span> <span class="hl-number">14</span>:<span class="hl-number">22</span>:<span class="hl-number">25.475</span> INFO <span class="hl-number">41050</span> --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/<span class="hl-number">0</span>p/xwq47sq106x1_g3dtv6qfm940000gq/T/contracts100276532569594265]
|
|
<span class="hl-number">2016</span>-<span class="hl-number">07</span>-<span class="hl-number">19</span> <span class="hl-number">14</span>:<span class="hl-number">22</span>:<span class="hl-number">27.737</span> INFO <span class="hl-number">41050</span> --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.example:http-server:<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT:stubs=<span class="hl-number">8080</span>}]</pre><p>Which means that Stub Runner has found your stubs and started a server for app with group id <code class="literal">com.example</code>, artifact id <code class="literal">http-server</code> with version <code class="literal">0.0.1-SNAPSHOT</code> of the stubs and with <code class="literal">stubs</code> classifier on port <code class="literal">8080</code>.</p><p><span class="strong"><strong>file a PR</strong></span></p><p>What we did until now is an iterative process. We can play around with the contract, install it locally and work on the consumer side until we’re happy with the contract.</p><p>Once we’re satisfied with the results and the test passes publish a PR to the server side. Currently the consumer side work is done.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_producer_side_fraud_detection_server" href="#_producer_side_fraud_detection_server"></a>79.4.3 Producer side (Fraud Detection server)</h3></div></div></div><p>As a developer of the Fraud Detection server (a server to the Loan Issuance service):</p><p><span class="strong"><strong>initial implementation</strong></span></p><p>As a reminder here you can see the initial implementation</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RequestMapping(value = "/fraudcheck", method = PUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> FraudCheckResult fraudCheck(<em><span class="hl-annotation" style="color: gray">@RequestBody</span></em> FraudCheck fraudCheck) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> FraudCheckResult(FraudCheckStatus.OK, NO_REASON);
|
|
}</pre><p><span class="strong"><strong>take over the PR</strong></span></p><pre class="programlisting">git checkout -b contract-change-pr master
|
|
git pull https://your-git-server.com/server-side-fork.git contract-change-pr</pre><p>You have to add the dependencies needed by the autogenerated tests</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-contract-verifier<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p>In the configuration of the Maven plugin we passed the <code class="literal">packageWithBaseClasses</code> property</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><extensions></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></extensions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>com.example.fraud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>We’ve decided to use the "convention based" naming by setting the <code class="literal">packageWithBaseClasses</code> property.
|
|
That means that 2 last packages will be combined into a name of the base test class. In our case the contracts
|
|
were placed under <code class="literal">src/test/resources/contracts/fraud</code>. Since we don’t have 2 packages starting from the <code class="literal">contracts</code>
|
|
folder we’re picking only one which is <code class="literal">fraud</code>. We’re adding the <code class="literal">Base</code> suffix and we’re capitalizing <code class="literal">fraud</code>.
|
|
That gives us the <code class="literal">FraudBase</code> test class name.</p></td></tr></table></div><p>That’s because all the generated tests will extend that class. Over there you can set up your Spring Context or
|
|
whatever is necessary. In our case we’re using <a class="link" href="http://rest-assured.io/" target="_top">Rest Assured MVC</a> to start the server side <code class="literal">FraudDetectionController</code>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.example.fraud;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.junit.Before;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> io.restassured.module.mockmvc.RestAssuredMockMvc;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> FraudBase {
|
|
<em><span class="hl-annotation" style="color: gray">@Before</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> setup() {
|
|
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> FraudDetectionController(),
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> FraudStatsController(stubbedStatsProvider()));
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> StatsProvider stubbedStatsProvider() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> fraudType -> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">switch</span> (fraudType) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">case</span> DRUNKS:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span class="hl-number">100</span>;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">case</span> ALL:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span class="hl-number">200</span>;
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span class="hl-number">0</span>;
|
|
};
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> assertThatRejectionReasonIsNull(Object rejectionReason) {
|
|
assert rejectionReason == null;
|
|
}
|
|
}</pre><p>Now, if you run the <code class="literal">./mvnw clean install</code> you would get sth like this:</p><pre class="programlisting">Results :
|
|
|
|
Tests in error:
|
|
ContractVerifierTest.validate_shouldMarkClientAsFraud:<span class="hl-number">32</span> » IllegalState Parsed...</pre><p>That’s because you have a new contract from which a test was generated and it failed since you haven’t implemented the feature. The autogenerated test would look like this:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> validate_shouldMarkClientAsFraud() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json"</span>)
|
|
.body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"client.id\":\"1234567890\",\"loanAmount\":99999}"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.put(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/fraudcheck"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);
|
|
assertThat(response.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1.json.*"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['fraudCheckStatus']"</span>).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[A-Z]{5}"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['rejection.reason']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Amount too high"</span>);
|
|
}</pre><p>As you can see all the <code class="literal">producer()</code> parts of the Contract that were present in the <code class="literal">value(consumer(…​), producer(…​))</code> blocks got injected into the test.</p><p>What’s important here to note is that on the producer side we also are doing TDD. We have expectations in form of a test. This test is shooting a request to our own application to an URL, headers and body defined in the contract. It also is expecting very precisely defined values in the response. In other words you have is your <code class="literal">red</code> part of <code class="literal">red</code>, <code class="literal">green</code> and <code class="literal">refactor</code>. Time to convert the <code class="literal">red</code> into the <code class="literal">green</code>.</p><p><span class="strong"><strong>write the missing implementation</strong></span></p><p>Now since we now what is the expected input and expected output let’s write the missing implementation.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RequestMapping(value = "/fraudcheck", method = PUT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> FraudCheckResult fraudCheck(<em><span class="hl-annotation" style="color: gray">@RequestBody</span></em> FraudCheck fraudCheck) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (amountGreaterThanThreshold(fraudCheck)) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> FraudCheckResult(FraudCheckStatus.FRAUD, AMOUNT_TOO_HIGH);
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> FraudCheckResult(FraudCheckStatus.OK, NO_REASON);
|
|
}</pre><p>If we execute <code class="literal">./mvnw clean install</code> again the tests will pass. Since the <code class="literal">Spring Cloud Contract Verifier</code> plugin adds the tests to the <code class="literal">generated-test-sources</code> you can actually run those tests from your IDE.</p><p><span class="strong"><strong>deploy your app</strong></span></p><p>Once you’ve finished your work it’s time to deploy your change. First merge the branch</p><pre class="programlisting">git checkout master
|
|
git merge --no-ff contract-change-pr
|
|
git push origin master</pre><p>Then we assume that your CI would run sth like <code class="literal">./mvnw clean deploy</code> which would publish both the application and the stub artifcats.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_consumer_side_loan_issuance_final_step" href="#_consumer_side_loan_issuance_final_step"></a>79.4.4 Consumer side (Loan Issuance) final step</h3></div></div></div><p>As a developer of the Loan Issuance service (a consumer of the Fraud Detection server):</p><p><span class="strong"><strong>merge branch to master</strong></span></p><pre class="programlisting">git checkout master
|
|
git merge --no-ff contract-change-pr</pre><p><span class="strong"><strong>work online</strong></span></p><p>Now you can disable the offline work for Spring Cloud Contract Stub Runner and provide where the repository with your stubs is placed. At this moment the stubs of the server side will be automatically downloaded from Nexus / Artifactory.
|
|
You can switch off the value of the <code class="literal">workOffline</code> parameter in your annotation. Below you can see an
|
|
example of achieving the same by changing the properties.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">stubrunner</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ids</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example:http-server-dsl:+:stubs:8080'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repositoryRoot</span>: http://repo.spring.io/libs-snapshot</pre><p>And that’s it!</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_dependencies" href="#_dependencies"></a>79.5 Dependencies</h2></div></div></div><p>The best way to add the dependencies is to just use the proper <code class="literal">starter</code> dependency.</p><p>For <code class="literal">stub-runner</code> use <code class="literal">spring-cloud-starter-stub-runner</code> and when you’re using a plugin just add
|
|
<code class="literal">spring-cloud-starter-contract-verifier</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_additional_links" href="#_additional_links"></a>79.6 Additional links</h2></div></div></div><p>Below you can find some resources related to Spring Cloud Contract Verifier and Stub Runner. Note that some can be outdated since the Spring Cloud Contract Verifier project
|
|
is under constant development.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spring_cloud_contract_video" href="#_spring_cloud_contract_video"></a>79.6.1 Spring Cloud Contract video</h3></div></div></div><p>You can check out the video from the Warsaw JUG about Spring Cloud Contract:</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_readings" href="#_readings"></a>79.6.2 Readings</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="http://www.slideshare.net/MarcinGrzejszczak/stick-to-the-rules-consumer-driven-contracts-201507-confitura" target="_top">Slides from Marcin Grzejszczak’s talk about Accurest</a></li><li class="listitem"><a class="link" href="http://toomuchcoding.com/blog/categories/accurest/" target="_top">Accurest related articles from Marcin Grzejszczak’s blog</a></li><li class="listitem"><a class="link" href="http://toomuchcoding.com/blog/categories/spring-cloud-contract/" target="_top">Spring Cloud Contract related articles from Marcin Grzejszczak’s blog</a></li><li class="listitem"><a class="link" href="http://groovy-lang.org/json.html" target="_top">Groovy docs regarding JSON</a></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_samples_2" href="#_samples_2"></a>79.7 Samples</h2></div></div></div><p>Here you can find some <a class="link" href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples" target="_top">samples</a>.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_contract_verifier_setup" href="#_spring_cloud_contract_verifier_setup"></a>80. Spring Cloud Contract Verifier Setup</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_gradle_project" href="#_gradle_project"></a>80.1 Gradle Project</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_prerequisites" href="#_prerequisites"></a>80.1.1 Prerequisites</h3></div></div></div><p>In order to use Spring Cloud Contract Verifier with WireMock you have to use Gradle or Maven plugin.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>If you want to use Spock in your projects you have to add separately
|
|
the <code class="literal">spock-core</code> and <code class="literal">spock-spring</code> modules. Check <a class="link" href="http://spockframework.github.io/" target="_top">Spock docs for more information</a></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_gradle_plugin_with_dependencies" href="#_add_gradle_plugin_with_dependencies"></a>80.1.2 Add gradle plugin with dependencies</h3></div></div></div><pre class="programlisting">buildscript {
|
|
repositories {
|
|
mavenCentral()
|
|
}
|
|
dependencies {
|
|
classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.boot:spring-boot-gradle-plugin:${springboot_version}"</span>
|
|
classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-contract-gradle-plugin:${verifier_version}"</span>
|
|
}
|
|
}
|
|
|
|
apply plugin: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'groovy'</span>
|
|
apply plugin: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'spring-cloud-contract'</span>
|
|
|
|
dependencyManagement {
|
|
imports {
|
|
mavenBom <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-contract-dependencies:${verifier_version}"</span>
|
|
}
|
|
}
|
|
|
|
dependencies {
|
|
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.codehaus.groovy:groovy-all:2.4.6'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// example with adding Spock core and Spock Spring</span>
|
|
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.spockframework:spock-core:1.0-groovy-2.4'</span>
|
|
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.spockframework:spock-spring:1.0-groovy-2.4'</span>
|
|
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud:spring-cloud-starter-contract-verifier'</span>
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_gradle_and_rest_assured_3_0" href="#_gradle_and_rest_assured_3_0"></a>80.1.3 Gradle and Rest Assured 3.0</h3></div></div></div><p>By default Rest Assured 2.x is added to the classpath. However in order to give the users the
|
|
opportunity to use Rest Assured 3.x it’s enough to add it to the plugins classpath.</p><pre class="programlisting">buildscript {
|
|
repositories {
|
|
mavenCentral()
|
|
}
|
|
dependencies {
|
|
classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.boot:spring-boot-gradle-plugin:${springboot_version}"</span>
|
|
classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-contract-gradle-plugin:${verifier_version}"</span>
|
|
classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"io.rest-assured:rest-assured:3.0.2"</span>
|
|
classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"io.rest-assured:spring-mock-mvc:3.0.2"</span>
|
|
}
|
|
}
|
|
|
|
depenendencies {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// all dependencies</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you can exclude rest-assured from spring-cloud-contract-verifier</span>
|
|
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"io.rest-assured:rest-assured:3.0.2"</span>
|
|
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"io.rest-assured:spring-mock-mvc:3.0.2"</span>
|
|
}</pre><p>That way the plugin will automatically see that Rest Assured 3.x is present on the classpath
|
|
and will modify the imports accordingly.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_snapshot_versions_for_gradle" href="#_snapshot_versions_for_gradle"></a>80.1.4 Snapshot versions for Gradle</h3></div></div></div><p>Add the additional snapshot repository to your build.gradle to use snapshot versions which are automatically uploaded after every successful build:</p><pre class="programlisting">buildscript {
|
|
repositories {
|
|
mavenCentral()
|
|
mavenLocal()
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/snapshot"</span> }
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/milestone"</span> }
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/release"</span> }
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_stubs" href="#_add_stubs"></a>80.1.5 Add stubs</h3></div></div></div><p>By default Spring Cloud Contract Verifier is looking for stubs in <code class="literal">src/test/resources/contracts</code> directory.</p><p>Directory containing stub definitions is treated as a class name, and each stub definition is treated as a single test.
|
|
We assume that it contains at least one directory which will be used as test class name. If there is more than one level of nested directories all except the last one will be used as package name.
|
|
So with following structure</p><pre class="programlisting">src/test/resources/contracts/myservice/shouldCreateUser.groovy
|
|
src/test/resources/contracts/myservice/shouldReturnUser.groovy</pre><p>Spring Cloud Contract Verifier will create test class <code class="literal">defaultBasePackage.MyService</code> with two methods</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">shouldCreateUser()</code></li><li class="listitem"><code class="literal">shouldReturnUser()</code></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_run_plugin" href="#_run_plugin"></a>80.1.6 Run plugin</h3></div></div></div><p>Plugin registers itself to be invoked before <code class="literal">check</code> task. You have nothing to do as long as you want it to be part of your build process. If you just want to generate tests please invoke <code class="literal">generateContractTests</code> task.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_default_setup" href="#_default_setup"></a>80.1.7 Default setup</h3></div></div></div><p>Default Gradle Plugin setup creates the following Gradle part of the build (it’s a pseudocode)</p><pre class="programlisting">contracts {
|
|
targetFramework = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'JUNIT'</span>
|
|
testMode = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'MockMvc'</span>
|
|
generatedTestSourcesDir = project.file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.buildDir}/generated-test-sources/contracts"</span>)
|
|
contractsDslDir = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.rootDir}/src/test/resources/contracts"</span>
|
|
basePackageForTests = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.verifier.tests'</span>
|
|
stubsOutputDir = project.file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.buildDir}/stubs"</span>)
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the following properties are used when you want to provide where the JAR with contract lays</span>
|
|
contractDependency {
|
|
stringNotation = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>
|
|
}
|
|
contractsPath = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>
|
|
contractsWorkOffline = false
|
|
contractRepository {
|
|
cacheDownloadedContracts(true)
|
|
}
|
|
}
|
|
|
|
tasks.create(type: Jar, name: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'verifierStubsJar'</span>, dependsOn: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'generateClientStubs'</span>) {
|
|
baseName = project.name
|
|
classifier = contracts.stubsSuffix
|
|
from contractVerifier.stubsOutputDir
|
|
}
|
|
|
|
project.artifacts {
|
|
archives task
|
|
}
|
|
|
|
tasks.create(type: Copy, name: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'copyContracts'</span>) {
|
|
from contracts.contractsDslDir
|
|
into contracts.stubsOutputDir
|
|
}
|
|
|
|
verifierStubsJar.dependsOn <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'copyContracts'</span>
|
|
|
|
publishing {
|
|
publications {
|
|
stubs(MavenPublication) {
|
|
artifactId project.name
|
|
artifact verifierStubsJar
|
|
}
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configure_plugin" href="#_configure_plugin"></a>80.1.8 Configure plugin</h3></div></div></div><p>To change default configuration just add <code class="literal">contracts</code> snippet to your Gradle config</p><pre class="programlisting">contracts {
|
|
testMode = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'MockMvc'</span>
|
|
baseClassForTests = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.mycompany.tests'</span>
|
|
generatedTestSourcesDir = project.file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'src/generatedContract'</span>)
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configuration_options_4" href="#_configuration_options_4"></a>80.1.9 Configuration options</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>testMode</strong></span> - defines mode for acceptance tests. By default MockMvc which is based on Spring’s MockMvc. It can also be changed to <span class="strong"><strong>JaxRsClient</strong></span> or to <span class="strong"><strong>Explicit</strong></span> for real HTTP calls.</li><li class="listitem"><span class="strong"><strong>imports</strong></span> - array with imports that should be included in generated tests (for example ['org.myorg.Matchers']). By default empty array []</li><li class="listitem"><span class="strong"><strong>staticImports</strong></span> - array with static imports that should be included in generated tests(for example ['org.myorg.Matchers.*']). By default empty array []</li><li class="listitem"><span class="strong"><strong>basePackageForTests</strong></span> - specifies base package for all generated tests. By default set to org.springframework.cloud.verifier.tests</li><li class="listitem"><span class="strong"><strong>baseClassForTests</strong></span> - base class for all generated tests. By default <code class="literal">spock.lang.Specification</code> if using Spock tests.</li><li class="listitem"><span class="strong"><strong>packageWithBaseClasses</strong></span> - instead of providing a fixed value for base class you can provide a package where all the base classes lay. Takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>.</li><li class="listitem"><span class="strong"><strong>baseClassMappings</strong></span> - explicitly map contract package to a FQN of a base class. Takes precedence over <span class="strong"><strong>packageWithBaseClasses</strong></span> and <span class="strong"><strong>baseClassForTests</strong></span>.</li><li class="listitem"><span class="strong"><strong>ruleClassForTests</strong></span> - specifies Rule which should be added to generated test classes.</li><li class="listitem"><span class="strong"><strong>ignoredFiles</strong></span> - Ant matcher allowing defining stub files for which processing should be skipped. By default empty array []</li><li class="listitem"><span class="strong"><strong>contractsDslDir</strong></span> - directory containing contracts written using the GroovyDSL. By default <code class="literal">$rootDir/src/test/resources/contracts</code></li><li class="listitem"><span class="strong"><strong>generatedTestSourcesDir</strong></span> - test source directory where tests generated from Groovy DSL should be placed. By default <code class="literal">$buildDir/generated-test-sources/contractVerifier</code></li><li class="listitem"><span class="strong"><strong>stubsOutputDir</strong></span> - dir where the generated WireMock stubs from Groovy DSL should be placed</li><li class="listitem"><span class="strong"><strong>targetFramework</strong></span> - the target test framework to be used; currently Spock and JUnit are supported with JUnit being the default framework</li></ul></div><p>The following properties are used when you want to provide where the JAR with contract lays</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>contractDependency</strong></span> - the Dependency that provides <code class="literal">groupid:artifactid:version:classifier</code> coordinates. You can use the <code class="literal">contractDependency</code> closure to set it up</li><li class="listitem"><span class="strong"><strong>contractsPath</strong></span> - if contract deps are downloaded will default to <code class="literal">groupid/artifactid</code> where <code class="literal">groupid</code> will be slash separated. Otherwise will scan contracts under provided directory</li><li class="listitem"><span class="strong"><strong>contractsWorkOffline</strong></span> - in order not to download the dependencies each time you can download them once and work offline afterwards (reuse local Maven repo)</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_single_base_class_for_all_tests" href="#_single_base_class_for_all_tests"></a>80.1.10 Single base class for all tests</h3></div></div></div><p>When using Spring Cloud Contract Verifier in default MockMvc you need to create a base specification for all generated acceptance tests. In this class you need to point to endpoint which should be verified.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">abstract</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> BaseMockMvcSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
|
|
def setup() {
|
|
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> PairIdController())
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> isProperCorrelationId(Integer correlationId) {
|
|
assert correlationId == <span class="hl-number">123456</span>
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> isEmpty(String value) {
|
|
assert value == null
|
|
}
|
|
|
|
}</pre><p>In case of using <code class="literal">Explicit</code> mode, you can use base class to initialize the whole tested app similarly as in regular integration tests. In case of <code class="literal">JAXRSCLIENT</code> mode this base class
|
|
should also contain <code class="literal">protected WebTarget webTarget</code> field, right now the only option to test JAX-RS API is to start a web server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_different_base_classes_for_contracts" href="#_different_base_classes_for_contracts"></a>80.1.11 Different base classes for contracts</h3></div></div></div><p>If your base classes differ between contracts you can tell the Spring Cloud Contract plugin which class should get
|
|
extended by the autogenerated tests. You have two options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">follow a convention by providing the <code class="literal">packageWithBaseClasses</code></li><li class="listitem">provide explicit mapping via <code class="literal">baseClassMappings</code></li></ul></div><p><span class="strong"><strong>Convention</strong></span></p><p>The convention is such that if you have a contract under e.g. <code class="literal">src/test/resources/contract/foo/bar/baz/</code> and provide the value of the <code class="literal">packageWithBaseClasses</code> property
|
|
to <code class="literal">com.example.base</code> then we will assume that there is a <code class="literal">BarBazBase</code> class under <code class="literal">com.example.base</code> package. In other words we take last two parts of package
|
|
if they exist and form a class with a <code class="literal">Base</code> suffix. Takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>. Example of usage in the <code class="literal">contracts</code> closure:</p><pre class="programlisting">packageWithBaseClasses = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example.base'</span></pre><p><span class="strong"><strong>Mapping</strong></span></p><p>You can manually map a regular expression of the contract’s package to fully qualified name of the base class for the matched contract.
|
|
Let’s take a look at the following example:</p><pre class="programlisting">baseClassForTests = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example.FooBase"</span>
|
|
baseClassMappings {
|
|
baseClassMapping(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'.*/com/.*'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example.ComBase'</span>)
|
|
baseClassMapping(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'.*/bar/.*'</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example.BarBase'</span>)
|
|
}</pre><p>Let’s assume that you have contracts under
|
|
- <code class="literal">src/test/resources/contract/com/</code>
|
|
- <code class="literal">src/test/resources/contract/foo/</code></p><p>By providing the <code class="literal">baseClassForTests</code> we have a fallback in case mapping didn’t succeed (you could also provide
|
|
the <code class="literal">packageWithBaseClasses</code> as fallback). That way the tests generated from <code class="literal">src/test/resources/contract/com/</code> contracts
|
|
will be extending the <code class="literal">com.example.ComBase</code> whereas the rest of tests will extend <code class="literal">com.example.FooBase</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_invoking_generated_tests" href="#_invoking_generated_tests"></a>80.1.12 Invoking generated tests</h3></div></div></div><p>To ensure that provider side is complaint with defined contracts, you need to invoke:</p><pre class="programlisting">./gradlew generateContractTests <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spring_cloud_contract_verifier_on_consumer_side" href="#_spring_cloud_contract_verifier_on_consumer_side"></a>80.1.13 Spring Cloud Contract Verifier on consumer side</h3></div></div></div><p>In consumer service you need to configure Spring Cloud Contract Verifier plugin in exactly the same way as in case of provider. If you don’t want to use Stub Runner then you need to copy contracts stored in
|
|
<code class="literal">src/test/resources/contracts</code> and generate WireMock json stubs using:</p><pre class="programlisting">./gradlew generateClientStubs</pre><p>Note that <code class="literal">stubsOutputDir</code> option has to be set for stub generation to work.</p><p>When present, json stubs can be used in consumer automated tests.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ContextConfiguration(loader == SpringApplicationContextLoader, classes == Application)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> LoanApplicationServiceSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@ClassRule</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@Shared</span></em>
|
|
WireMockClassRule wireMockRule == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> WireMockClassRule()
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
LoanApplicationService sut
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should successfully apply for loan'</span>() {
|
|
given:
|
|
LoanApplication application =
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> LoanApplication(client: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Client(clientPesel: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'12345678901'</span>), amount: <span class="hl-number">123.123</span>)
|
|
when:
|
|
LoanApplicationResult loanApplication == sut.loanApplication(application)
|
|
then:
|
|
loanApplication.loanApplicationStatus == LoanApplicationStatus.LOAN_APPLIED
|
|
loanApplication.rejectionReason == null
|
|
}
|
|
}</pre><p>Underneath LoanApplication makes a call to FraudDetection service. This request is handled by WireMock server configured using stubs generated by Spring Cloud Contract Verifier.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_in_your_maven_project" href="#_using_in_your_maven_project"></a>80.2 Using in your Maven project</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_maven_plugin" href="#_add_maven_plugin"></a>80.2.1 Add maven plugin</h3></div></div></div><p>Add the Spring Cloud Contract BOM</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-dependencies.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span></pre><p>Next, the <code class="literal">Spring Cloud Contract Verifier</code> Maven plugin</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><extensions></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></extensions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>com.example.fraud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>You can read more in the <a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract-maven-plugin/" target="_top">Spring Cloud Contract Maven Plugin Docs</a></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_maven_and_rest_assured_3_0" href="#_maven_and_rest_assured_3_0"></a>80.2.2 Maven and Rest Assured 3.0</h3></div></div></div><p>By default Rest Assured 2.x is added to the classpath. However in order to give the users the
|
|
opportunity to use Rest Assured 3.x it’s enough to add it to the plugins classpath.</p><pre class="programlisting"><plugin>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
|
|
<version>${spring-cloud-contract.version}</version>
|
|
<extensions>true</extensions>
|
|
<configuration>
|
|
<packageWithBaseClasses>com.example</packageWithBaseClasses>
|
|
</configuration>
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.cloud</groupId>
|
|
<artifactId>spring-cloud-contract-verifier</artifactId>
|
|
<version>${spring-cloud-contract.version}</version>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>io.rest-assured</groupId>
|
|
<artifactId>rest-assured</artifactId>
|
|
<version><span class="hl-number">3.0</span>.<span class="hl-number">2</span></version>
|
|
<scope>compile</scope>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>io.rest-assured</groupId>
|
|
<artifactId>spring-mock-mvc</artifactId>
|
|
<version><span class="hl-number">3.0</span>.<span class="hl-number">2</span></version>
|
|
<scope>compile</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</plugin>
|
|
|
|
<dependencies>
|
|
<!-- all dependencies -->
|
|
<!-- you can exclude rest-assured from spring-cloud-contract-verifier -->
|
|
<dependency>
|
|
<groupId>io.rest-assured</groupId>
|
|
<artifactId>rest-assured</artifactId>
|
|
<version><span class="hl-number">3.0</span>.<span class="hl-number">2</span></version>
|
|
<scope>test</scope>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>io.rest-assured</groupId>
|
|
<artifactId>spring-mock-mvc</artifactId>
|
|
<version><span class="hl-number">3.0</span>.<span class="hl-number">2</span></version>
|
|
<scope>test</scope>
|
|
</dependency>
|
|
</dependencies></pre><p>That way the plugin will automatically see that Rest Assured 3.x is present on the classpath
|
|
and will modify the imports accordingly.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_snapshot_versions_for_maven" href="#_snapshot_versions_for_maven"></a>80.2.3 Snapshot versions for Maven</h3></div></div></div><p>For Snapshot / Milestone versions you have to add the following section to your <code class="literal">pom.xml</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/snapshot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/milestone<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/release<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/snapshot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/milestone<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/release<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepositories></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_stubs_2" href="#_add_stubs_2"></a>80.2.4 Add stubs</h3></div></div></div><p>By default Spring Cloud Contract Verifier is looking for stubs in <code class="literal">src/test/resources/contracts</code> directory.
|
|
Directory containing stub definitions is treated as a class name, and each stub definition is treated as a single test.
|
|
We assume that it contains at least one directory which will be used as test class name. If there is more than one level of nested directories all except the last one will be used as package name.
|
|
So with following structure</p><pre class="programlisting">src/test/resources/contracts/myservice/shouldCreateUser.groovy
|
|
src/test/resources/contracts/myservice/shouldReturnUser.groovy</pre><p>Spring Cloud Contract Verifier will create test class <code class="literal">defaultBasePackage.MyService</code> with two methods
|
|
- <code class="literal">shouldCreateUser()</code>
|
|
- <code class="literal">shouldReturnUser()</code></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_run_plugin_2" href="#_run_plugin_2"></a>80.2.5 Run plugin</h3></div></div></div><p>Plugin goal <code class="literal">generateTests</code> is assigned to be invoked in phase <code class="literal">generate-test-sources</code>. You have nothing to do as long as you want it to be part of your build process. If you just want to generate tests please invoke <code class="literal">generateTests</code> goal.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configure_plugin_2" href="#_configure_plugin_2"></a>80.2.6 Configure plugin</h3></div></div></div><p>To change default configuration just add <code class="literal">configuration</code> section to plugin definition or <code class="literal">execution</code> definition.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>convert<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>generateStubs<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>generateTests<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><basePackageForTests></span>org.springframework.cloud.verifier.twitter.place<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></basePackageForTests></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassForTests></span>org.springframework.cloud.verifier.twitter.place.BaseMockMvcSpec<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassForTests></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_important_configuration_options" href="#_important_configuration_options"></a>80.2.7 Important configuration options</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>testMode</strong></span> - defines mode for acceptance tests. By default <code class="literal">MockMvc</code> which is based on Spring’s MockMvc. It can also be changed to <code class="literal">JaxRsClient</code> or to <code class="literal">Explicit</code> for real HTTP calls.</li><li class="listitem"><span class="strong"><strong>basePackageForTests</strong></span> - specifies base package for all generated tests. By default set to <code class="literal">org.springframework.cloud.verifier.tests</code>.</li><li class="listitem"><span class="strong"><strong>ruleClassForTests</strong></span> - specifies Rule which should be added to generated test classes.</li><li class="listitem"><span class="strong"><strong>baseClassForTests</strong></span> - base class for generated tests. By default <code class="literal">spock.lang.Specification</code> if using Spock tests.</li><li class="listitem"><span class="strong"><strong>contractsDirectory</strong></span> - directory containing contracts written using the GroovyDSL. By default <code class="literal">/src/test/resources/contracts</code>.</li><li class="listitem"><span class="strong"><strong>testFramework</strong></span> - the target test framework to be used; currently Spock and JUnit are supported with JUnit being the default framework</li><li class="listitem"><span class="strong"><strong>packageWithBaseClasses</strong></span> - instead of providing a fixed value for base class you can provide a package where all the base classes lay.
|
|
The convention is such that if you have a contract under <code class="literal">src/test/resources/contract/foo/bar/baz/</code> and provide the value of this property
|
|
to <code class="literal">com.example.base</code> then we will assume that there is a <code class="literal">BarBazBase</code> class under <code class="literal">com.example.base</code> package. Takes precedence
|
|
over <span class="strong"><strong>baseClassForTests</strong></span></li><li class="listitem"><span class="strong"><strong>baseClassMappings</strong></span> - list of base class mappings that where you have to provide <code class="literal">contractPackageRegex</code> which is checked
|
|
against the package in which the contract lays and <code class="literal">baseClassFQN</code> that maps to fully qualified name of the base class for the matched
|
|
contract. If you have a contract under <code class="literal">src/test/resources/contract/foo/bar/baz/</code> and map the property <code class="literal">.*</code> → <code class="literal">com.example.base.BaseClass</code> then
|
|
the test class generated from these contracts will extend <code class="literal">com.example.base.BaseClass</code>. Takes precedence over <span class="strong"><strong>packageWithBaseClasses</strong></span>
|
|
and <span class="strong"><strong>baseClassForTests</strong></span>.</li></ul></div><p>If you want to download your contract definitions from a Maven repository you can use</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>contractDependency</strong></span> - the contract dependency that contains all the packaged contracts</li><li class="listitem"><span class="strong"><strong>contractsPath</strong></span> - path to concrete contracts in the JAR with packaged contracts. Defaults to <code class="literal">groupid/artifactid</code> where <code class="literal">gropuid</code> is slash separated.</li><li class="listitem"><span class="strong"><strong>contractsWorkOffline</strong></span> - if the dependencies should be downloaded or local Maven only should be reused</li><li class="listitem"><span class="strong"><strong>contractsRepositoryUrl</strong></span> - <span class="strong"><strong>DEPRECATED PROPERTY - please use the <code class="literal">contractRepository</code> closure</strong></span> - URL to a repo with the artifacts with contracts, if not provided should use the current Maven ones</li><li class="listitem"><p class="simpara"><span class="strong"><strong>contractRepository</strong></span> - closure where you can define properties related to repository with contracts</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><span class="strong"><strong>username</strong></span> - username to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>password</strong></span> - username to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>proxyHost</strong></span> - proxy host to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>proxyPort</strong></span> - proxy port to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>cacheDownloadedContracts</strong></span> - if you want to reuse download JARs that contain contract definitions.
|
|
We cache only non-snapshot, explicitly provided versions (e.g. <code class="literal">+</code> or <code class="literal">1.0.0.BUILD-SNAPSHOT</code> won’t get cached).
|
|
By default this feature is turned on.</li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_single_base_class_for_all_tests_2" href="#_single_base_class_for_all_tests_2"></a>80.2.8 Single base class for all tests</h3></div></div></div><p>When using Spring Cloud Contract Verifier in default MockMvc you need to create a base specification for all generated acceptance tests.
|
|
In this class you need to point to endpoint which should be verified.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.mycompany.tests
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.mycompany.ExampleSpringController
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.jayway.restassured.module.mockmvc.RestAssuredMockMvc
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> spock.lang.Specification
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MvcSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
def setup() {
|
|
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ExampleSpringController())
|
|
}
|
|
}</pre><p>In case of using <code class="literal">Explicit</code> mode, you can use base class to initialize the whole tested app similarly as in regular integration tests. In case of <code class="literal">JAXRSCLIENT</code> mode this base class should also contain <code class="literal">protected WebTarget webTarget</code> field, right now the only option to test JAX-RS API is to start a web server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_different_base_classes_for_contracts_2" href="#_different_base_classes_for_contracts_2"></a>80.2.9 Different base classes for contracts</h3></div></div></div><p>If your base classes differ between contracts you can tell the Spring Cloud Contract plugin which class should get
|
|
extended by the autogenerated tests. You have two options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">follow a convention by providing the <code class="literal">packageWithBaseClasses</code></li><li class="listitem">provide explicit mapping via <code class="literal">baseClassMappings</code></li></ul></div><p><span class="strong"><strong>Convention</strong></span></p><p>The convention is such that if you have a contract under e.g. <code class="literal">src/test/resources/contract/hello/v1/</code> and provide the value of the <code class="literal">packageWithBaseClasses</code> property
|
|
to <code class="literal">hello</code> then we will assume that there is a <code class="literal">HelloV1Base</code> class under <code class="literal">hello</code> package. In other words we take last two parts of package
|
|
if they exist and form a class with a <code class="literal">Base</code> suffix. Takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>. Example of usage:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>hello<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p><span class="strong"><strong>Mapping</strong></span></p><p>You can manually map a regular expression of the contract’s package to fully qualified name of the base class for the matched contract.
|
|
You have to provide a list <code class="literal">baseClassMappings</code> of <code class="literal">baseClassMapping</code> that takes a <code class="literal">contractPackageRegex</code> to <code class="literal">baseClassFQN</code> mapping.
|
|
Let’s take a look at the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassForTests></span>com.example.FooBase<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassForTests></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassMappings></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassMapping></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><contractPackageRegex></span>.*com.*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></contractPackageRegex></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassFQN></span>com.example.TestBase<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassFQN></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassMapping></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassMappings></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>Let’s assume that you have contracts under
|
|
- <code class="literal">src/test/resources/contract/com/</code>
|
|
- <code class="literal">src/test/resources/contract/foo/</code></p><p>By providing the <code class="literal">baseClassForTests</code> we have a fallback in case mapping didn’t succeed (you could also provide
|
|
the <code class="literal">packageWithBaseClasses</code> as fallback). That way the tests generated from <code class="literal">src/test/resources/contract/com/</code> contracts
|
|
will be extending the <code class="literal">com.example.ComBase</code> whereas the rest of tests will extend <code class="literal">com.example.FooBase</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_invoking_generated_tests_2" href="#_invoking_generated_tests_2"></a>80.2.10 Invoking generated tests</h3></div></div></div><p>Spring Cloud Contract Maven Plugin generates verification code into directory <code class="literal">/generated-test-sources/contractVerifier</code> and attach this directory to <code class="literal">testCompile</code> goal.</p><p>For Groovy Spock code use:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.codehaus.gmavenplus<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>gmavenplus-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>1.5<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>testCompile<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><testSources></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><testSource></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><directory></span>${project.basedir}/src/test/groovy<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></directory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include></span>**/*.groovy<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></include></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></testSource></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><testSource></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><directory></span>${project.build.directory}/generated-test-sources/contractVerifier<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></directory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include></span>**/*.groovy<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></include></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></testSource></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></testSources></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>To ensure that provider side is complaint with defined contracts, you need to invoke <code class="literal">mvn generateTest test</code></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_faq_with_maven_plugin" href="#_faq_with_maven_plugin"></a>80.2.11 FAQ with Maven Plugin</h3></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_maven_plugin_and_sts" href="#_maven_plugin_and_sts"></a>80.2.12 Maven Plugin and STS</h3></div></div></div><p>In case you see the following exception while using STS</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/1.0.x/docs/src/main/asciidoc/images/sts_exception.png" alt="STS Exception"></div></div><p>when you click on the marker you should see sth like this</p><pre class="programlisting"> plugin:<span class="hl-number">1.1</span>.<span class="hl-number">0.</span>M1:convert:default-convert:process-<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
|
|
cloud-contract-maven-plugin:<span class="hl-number">1.1</span>.<span class="hl-number">0.</span>M1:convert failed. at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:<span class="hl-number">145</span>) at
|
|
org.eclipse.m2e.core.internal.embedder.MavenImpl.execute(MavenImpl.java:<span class="hl-number">331</span>) at org.eclipse.m2e.core.internal.embedder.MavenImpl$<span class="hl-number">11.</span>call(MavenImpl.java:<span class="hl-number">1362</span>) at
|
|
...
|
|
org.eclipse.core.internal.jobs.Worker.run(Worker.java:<span class="hl-number">55</span>) Caused by: java.lang.NullPointerException at
|
|
org.eclipse.m2e.core.internal.builder.plexusbuildapi.EclipseIncrementalBuildContext.hasDelta(EclipseIncrementalBuildContext.java:<span class="hl-number">53</span>) at
|
|
org.sonatype.plexus.build.incremental.ThreadBuildContext.hasDelta(ThreadBuildContext.java:<span class="hl-number">59</span>) at</pre><p>In order to fix this issue just provide the following section in your <code class="literal">pom.xml</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><build></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginManagement></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugins></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!--This plugin's configuration is used to store Eclipse m2e settings
|
|
only. It has no influence on the Maven build itself. --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.eclipse.m2e<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>lifecycle-mapping<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>1.0.0<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><lifecycleMappingMetadata></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginExecutions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginExecution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginExecutionFilter></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><versionRange></span>[1.0,)<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></versionRange></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>convert<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginExecutionFilter></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><action></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><execute /></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></action></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginExecution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginExecutions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></lifecycleMappingMetadata></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugins></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginManagement></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></build></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spring_cloud_contract_verifier_on_consumer_side_2" href="#_spring_cloud_contract_verifier_on_consumer_side_2"></a>80.2.13 Spring Cloud Contract Verifier on consumer side</h3></div></div></div><p>You can actually use the Spring Cloud Contract Verifier also for the consumer side!
|
|
You can use the plugin so that it only converts the contracts and generates the stubs.
|
|
To achieve that you need to configure Spring Cloud Contract Verifier plugin in exactly
|
|
the same way as in case of provider. You need to copy contracts stored in
|
|
<code class="literal">src/test/resources/contracts</code> and generate WireMock json stubs using:
|
|
<code class="literal">mvn generateStubs</code> command. By default generated WireMock mapping is
|
|
stored in directory <code class="literal">target/mappings</code>. Your project should create from
|
|
this generated mappings additional artifact with classifier <code class="literal">stubs</code> for
|
|
easy deploy to maven repository.</p><p>Sample configuration:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${verifier-plugin.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>convert<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>generateStubs<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>When present, json stubs can be used in consumer automated tests.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringTestRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> LoanApplicationServiceTests {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
LoanApplicationService service;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> shouldSuccessfullyApplyForLoan() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//given:</span>
|
|
LoanApplication application =
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> LoanApplication(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Client(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"12345678901"</span>), <span class="hl-number">123.123</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//when:</span>
|
|
LoanApplicationResult loanApplication = service.loanApplication(application);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(loanApplication.loanApplicationStatus).isEqualTo(LoanApplicationStatus.LOAN_APPLIED);
|
|
assertThat(loanApplication.rejectionReason).isNull();
|
|
}
|
|
}</pre><p>Underneath <code class="literal">LoanApplication</code> makes a call to the <code class="literal">FraudDetection</code> service. This request is handled by
|
|
a WireMock server configured using stubs generated by Spring Cloud Contract Verifier.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_scenarios" href="#_scenarios"></a>80.3 Scenarios</h2></div></div></div><p>It’s possible to handle scenarios with Spring Cloud Contract Verifier. All you need to do is to stick to proper naming convention while creating your contracts. The convention requires to include order number followed by the underscore.</p><pre class="screen">my_contracts_dir\
|
|
scenario1\
|
|
1_login.groovy
|
|
2_showCart.groovy
|
|
3_logout.groovy</pre><p>Such tree will cause Spring Cloud Contract Verifier generating WireMock’s scenario with name <code class="literal">scenario1</code> and three steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">login marked as <code class="literal">Started</code> pointing to:</li><li class="listitem">showCart marked as <code class="literal">Step1</code> pointing to:</li><li class="listitem">logout marked as <code class="literal">Step2</code> which will close the scenario.</li></ul></div><p>More details about WireMock scenarios can be found under <a class="link" href="http://wiremock.org/stateful-behaviour.html" target="_top">http://wiremock.org/stateful-behaviour.html</a></p><p>Spring Cloud Contract Verifier will also generate tests with guaranteed order of execution.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stubs_and_transitive_dependencies" href="#_stubs_and_transitive_dependencies"></a>80.4 Stubs and transitive dependencies</h2></div></div></div><p>The Maven and Gradle plugin that we’re created are adding the tasks that create the stubs jar for you. What can be problematic
|
|
is that when reusing the stubs you can by mistake import all of that stub dependencies! When building a Maven artifact
|
|
even though you have a couple of different jars, all of them share one pom:</p><pre class="programlisting">├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075506</span>-<span class="hl-number">1</span>-stubs.jar
|
|
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075506</span>-<span class="hl-number">1</span>-stubs.jar.sha1
|
|
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075655</span>-<span class="hl-number">2</span>-stubs.jar
|
|
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075655</span>-<span class="hl-number">2</span>-stubs.jar.sha1
|
|
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-SNAPSHOT.jar
|
|
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-SNAPSHOT.pom
|
|
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-SNAPSHOT-stubs.jar
|
|
├── ...
|
|
└── ...</pre><p>There are three possibilities of working with those dependencies so as not to have any issues with transitive dependencies.</p><p><span class="strong"><strong>Mark all application dependencies as optional</strong></span></p><p>If in the <code class="literal">github-webhook</code> application we would mark all of our dependencies as optional, when you include the
|
|
<code class="literal">github-webhook</code> stubs in another application (or when that dependency gets downloaded by Stub Runner) then, since
|
|
all of the depenencies are optional, they will not get downloaded.</p><p><span class="strong"><strong>Create a separate artifactid for stubs</strong></span></p><p>If you create a separate artifactid then you can set it up in whatever way you wish. For example by having no dependencies at all.</p><p><span class="strong"><strong>Exclude dependencies on the consumer side</strong></span></p><p>As a consumer, if you add the stub dependency to your classpath you can explicitly exclude the unwanted dependencies.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_contract_verifier_messaging" href="#_spring_cloud_contract_verifier_messaging"></a>81. Spring Cloud Contract Verifier Messaging</h2></div></div></div><p>Spring Cloud Contract Verifier allows you to verify your application that uses messaging as means of communication.
|
|
All of our integrations are working with Spring but you can also create one yourself and use it.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_integrations_2" href="#_integrations_2"></a>81.1 Integrations</h2></div></div></div><p>You can use one of the four integration configurations:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Apache Camel</li><li class="listitem">Spring Integration</li><li class="listitem">Spring Cloud Stream</li><li class="listitem">Spring AMQP</li></ul></div><p>Since we’re using Spring Boot then if you have added one of the aforementioned libraries
|
|
to the classpath then automatically all the messaging configuration will be set up.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Remember to put <code class="literal">@AutoConfigureMessageVerifier</code> on the base class of your
|
|
generated tests. Otherwise messaging part of Spring Cloud Contract Verifier will not work.</p></td></tr></table></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you want to use Spring Cloud Stream remember to add a
|
|
<code class="literal">org.springframework.cloud:spring-cloud-stream-test-support</code> dependency.</p></td></tr></table></div><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-test-support<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-stream-test-support"</span></pre><p class="secondary">
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_manual_integration_testing" href="#_manual_integration_testing"></a>81.2 Manual Integration Testing</h2></div></div></div><p>The main interface used by the tests is the <code class="literal">org.springframework.cloud.contract.verifier.messaging.MessageVerifier</code>.
|
|
It defines how to send and receive messages. You can create your own implementation to achieve the
|
|
same goal.</p><p>In the a test you can inject a <code class="literal">ContractVerifierMessageExchange</code> to send and receive messages that follow the contract.
|
|
Then add <code class="literal">@AutoConfigureMessageVerifier</code> to your test, e.g.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringTestRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureMessageVerifier</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MessagingContractTests {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> MessageVerifier verifier;
|
|
...
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If your tests require stubs as well, then
|
|
<code class="literal">@AutoConfigureStubRunner</code> includes the messaging configuration, so
|
|
you only need the one annotation.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_publisher_side_test_generation" href="#_publisher_side_test_generation"></a>81.3 Publisher side test generation</h2></div></div></div><p>Having the <code class="literal">input</code> or <code class="literal">outputMessage</code> sections in your DSL will result in creation of tests on the publisher’s side. By default
|
|
JUnit tests will be created, however there is also a possibility to create Spock tests.</p><p>There are 3 main scenarios that we should take into consideration:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Scenario 1: there is no input message that produces an output one. The output message is triggered by a component
|
|
inside the application (e.g. scheduler)</li><li class="listitem">Scenario 2: the input message triggers an output message</li><li class="listitem">Scenario 3: the input message is consumed and there is no output message</li></ul></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>The destination passed to <code class="literal">messageFrom</code> or <code class="literal">sentTo</code> can have different meanings for different
|
|
messaging implementations. For <span class="strong"><strong>Stream</strong></span> and <span class="strong"><strong>Integration</strong></span> it’s first resolved as a <code class="literal">destination</code> of a channel, and then if
|
|
there is no such <code class="literal">destination</code> it’s resolved as a channel name. For <span class="strong"><strong>Camel</strong></span> that’s a certain component (e.x. <code class="literal">jms</code>).</p></td></tr></table></div><p>Example for Camel:</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_scenario_1_no_input_message" href="#_scenario_1_no_input_message"></a>81.3.1 Scenario 1 (no input message)</h3></div></div></div><p>For the given contract:</p><pre class="programlisting">def contractDsl = Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'some_label'</span>
|
|
input {
|
|
triggeredBy(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookReturnedTriggered()'</span>)
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'activemq:output'</span>)
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{ "bookName" : "foo" }'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
messagingContentType(applicationJson())
|
|
}
|
|
}
|
|
}</pre><p>The following JUnit test will be created:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
bookReturnedTriggered();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
ContractVerifierMessage response = contractVerifierMessaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"activemq:output"</span>);
|
|
assertThat(response).isNotNull();
|
|
assertThat(response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"BOOK-NAME"</span>)).isNotNull();
|
|
assertThat(response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"BOOK-NAME"</span>).toString()).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>);
|
|
assertThat(response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"contentType"</span>)).isNotNull();
|
|
assertThat(response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"contentType"</span>).toString()).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()));
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bookName"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre><p>And the following Spock test would be created:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span> when:
|
|
bookReturnedTriggered()
|
|
|
|
then:
|
|
ContractVerifierMessage response = contractVerifierMessaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'activemq:output'</span>)
|
|
assert response != null
|
|
response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>)?.toString() == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'contentType'</span>)?.toString() == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>
|
|
and:
|
|
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.payload))
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bookName"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>)
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_scenario_2_output_triggered_by_input" href="#_scenario_2_output_triggered_by_input"></a>81.3.2 Scenario 2 (output triggered by input)</h3></div></div></div><p>For the given contract:</p><pre class="programlisting">def contractDsl = Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'some_label'</span>
|
|
input {
|
|
messageFrom(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:input'</span>)
|
|
messageBody([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
messageHeaders {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>)
|
|
}
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>)
|
|
body([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
}
|
|
}
|
|
}</pre><p>The following JUnit test will be created:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\\"</span>bookName\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span>foo\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"}"</span>
|
|
, headers()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"sample"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"header"</span>));
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
contractVerifierMessaging.send(inputMessage, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"jms:input"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
ContractVerifierMessage response = contractVerifierMessaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"jms:output"</span>);
|
|
assertThat(response).isNotNull();
|
|
assertThat(response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"BOOK-NAME"</span>)).isNotNull();
|
|
assertThat(response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"BOOK-NAME"</span>).toString()).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()));
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bookName"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre><p>And the following Spock test would be created:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\
|
|
</span>given:
|
|
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{"bookName":"foo"}'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>,
|
|
[<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>]
|
|
)
|
|
|
|
when:
|
|
contractVerifierMessaging.send(inputMessage, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:input'</span>)
|
|
|
|
then:
|
|
ContractVerifierMessage response = contractVerifierMessaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>)
|
|
assert response !- null
|
|
response.getHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>)?.toString() == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
and:
|
|
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.payload))
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bookName"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_scenario_3_no_output_message" href="#_scenario_3_no_output_message"></a>81.3.3 Scenario 3 (no output message)</h3></div></div></div><p>For the given contract:</p><pre class="programlisting">def contractDsl = Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'some_label'</span>
|
|
input {
|
|
messageFrom(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:delete'</span>)
|
|
messageBody([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
messageHeaders {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>)
|
|
}
|
|
assertThat(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookWasDeleted()'</span>)
|
|
}
|
|
}</pre><p>The following JUnit test will be created:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\\"</span>bookName\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span>foo\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"}"</span>
|
|
, headers()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"sample"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"header"</span>));
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
contractVerifierMessaging.send(inputMessage, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"jms:delete"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
bookWasDeleted();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre><p>And the following Spock test would be created:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span>given:
|
|
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
|
|
\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'\'\'{"bookName":"foo"}\'\'\',
|
|
</span> [<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>]
|
|
)
|
|
|
|
when:
|
|
contractVerifierMessaging.send(inputMessage, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:delete'</span>)
|
|
|
|
then:
|
|
noExceptionThrown()
|
|
bookWasDeleted()
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_consumer_stub_side_generation" href="#_consumer_stub_side_generation"></a>81.4 Consumer Stub Side generation</h2></div></div></div><p>Unlike the HTTP part - in Messaging we need to publish the Groovy DSL inside the JAR with a stub. Then it’s parsed on the consumer side
|
|
and proper stubbed routes are created.</p><p>For more information please consult the Stub Runner Messaging sections.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-stream-rabbit<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-contract-stub-runner<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-test-support<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-dependencies<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>Dalston.BUILD-SNAPSHOT<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><type></span>pom<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></type></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">ext {
|
|
contractsDir = file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"mappings"</span>)
|
|
stubsOutputDirRoot = file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.buildDir}/production/${project.name}-stubs/"</span>)
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Automatically added by plugin:</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// copyContracts - copies contracts to the output folder from which JAR will be created</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// verifierStubsJar - JAR with a provided stub suffix</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the presented publication is also added by the plugin but you can modify it as you wish</span>
|
|
|
|
publishing {
|
|
publications {
|
|
stubs(MavenPublication) {
|
|
artifactId <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.name}-stubs"</span>
|
|
artifact verifierStubsJar
|
|
}
|
|
}
|
|
}</pre><p class="secondary">
|
|
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_contract_stub_runner" href="#_spring_cloud_contract_stub_runner"></a>82. Spring Cloud Contract Stub Runner</h2></div></div></div><p>One of the issues that you could have encountered while using Spring Cloud Contract Verifier was to pass the generated WireMock JSON stubs from the server side to the client side (or various clients).
|
|
The same takes place in terms of client side generation for messaging.</p><p>Copying the JSON files / setting the client side for messaging manually is out of the question.</p><p>That’s why we’ll introduce Spring Cloud Contract Stub Runner that can download and run the stubs
|
|
automatically for you.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_snapshot_versions" href="#_snapshot_versions"></a>82.1 Snapshot versions</h2></div></div></div><p>Add the additional snapshot repository to your build.gradle to use snapshot versions which are automatically uploaded after every successful build:</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/snapshot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/milestone<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/release<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></repositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepositories></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/snapshot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Milestones<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/milestone<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Releases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><url></span>https://repo.spring.io/release<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></url></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepositories></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">buildscript {
|
|
repositories {
|
|
mavenCentral()
|
|
mavenLocal()
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/snapshot"</span> }
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/milestone"</span> }
|
|
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/release"</span> }
|
|
}</pre><p class="secondary">
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_publishing_stubs_as_jars" href="#_publishing_stubs_as_jars"></a>82.2 Publishing stubs as JARs</h2></div></div></div><p>The easiest approach would be to centralize the way stubs are kept. For example you can keep them as JARs in a Maven repository.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>For both Maven and Gradle the setup comes out of the box. But you can customize it if you want to.</p></td></tr></table></div><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- First disable the default jar setup in the properties section--></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- we don't want the verifier to do a jar for us --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><spring.cloud.contract.verifier.skip></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></spring.cloud.contract.verifier.skip></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Next add the assembly plugin to your build --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- we want the assembly plugin to generate the JAR --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.apache.maven.plugins<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>maven-assembly-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>stub<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><phase></span>prepare-package<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></phase></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><goal></span>single<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goal></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goals></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><inherited></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></inherited></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><attach></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></attach></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><descriptor></span>$../../../../src/assembly/stub.xml<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></descriptor></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></execution></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></executions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- Finally setup your assembly. Below you can find the contents of src/main/assembly/stub.xml --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><assembly</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">xmlns</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">xmlns:xsi</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">xsi:schemaLocation</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>stubs<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><formats></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><format></span>jar<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></format></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></formats></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><includeBaseDirectory></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></includeBaseDirectory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileSets></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><directory></span>src/main/java<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></directory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><outputDirectory></span>/<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></outputDirectory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include></span>**com/example/model/*.*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></include></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><directory></span>${project.build.directory}/classes<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></directory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><outputDirectory></span>/<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></outputDirectory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include></span>**com/example/model/*.*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></include></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><directory></span>${project.build.directory}/snippets/stubs<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></directory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><outputDirectory></span>META-INF/${project.groupId}/${project.artifactId}/${project.version}/mappings<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></outputDirectory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include></span>**/*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></include></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><directory></span>$../../../../src/test/resources/contracts<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></directory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><outputDirectory></span>META-INF/${project.groupId}/${project.artifactId}/${project.version}/contracts<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></outputDirectory></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><include></span>**/*.groovy<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></include></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></includes></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileSet></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></fileSets></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></assembly></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">ext {
|
|
contractsDir = file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"mappings"</span>)
|
|
stubsOutputDirRoot = file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.buildDir}/production/${project.name}-stubs/"</span>)
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Automatically added by plugin:</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// copyContracts - copies contracts to the output folder from which JAR will be created</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// verifierStubsJar - JAR with a provided stub suffix</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the presented publication is also added by the plugin but you can modify it as you wish</span>
|
|
|
|
publishing {
|
|
publications {
|
|
stubs(MavenPublication) {
|
|
artifactId <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.name}-stubs"</span>
|
|
artifact verifierStubsJar
|
|
}
|
|
}
|
|
}</pre><p class="secondary">
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_core" href="#_stub_runner_core"></a>82.3 Stub Runner Core</h2></div></div></div><p>Runs stubs for service collaborators. Treating stubs as contracts of services allows to use stub-runner as an implementation of
|
|
<a class="link" href="http://martinfowler.com/articles/consumerDrivenContracts.html" target="_top">Consumer Driven Contracts</a>.</p><p>Stub Runner allows you to automatically download the stubs of the provided dependencies (or pick those from the classpath), start WireMock servers for them and feed them with proper stub definitions.
|
|
For messaging, special stub routes are defined.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_retrieving_stubs" href="#_retrieving_stubs"></a>82.3.1 Retrieving stubs</h3></div></div></div><p>You can pick the following options of acquiring stubs</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Aether based solution that downloads JARs with stubs from Artifactory / Nexus</li><li class="listitem">Classpath scanning solution that searches classpath via pattern to retrieve stubs</li><li class="listitem">Write your own implementation of the <code class="literal">org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder</code> for full customization</li></ul></div><p>The latter example is described in the <a class="link" href="#">Custom Stub Runner</a> section.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_stub_downloading" href="#_stub_downloading"></a>Stub downloading</h4></div></div></div><p>If you provide the <code class="literal">stubrunner.repositoryRoot</code> or <code class="literal">stubrunner.workOffline</code> flag will be set
|
|
to <code class="literal">true</code> then Stub Runner will connect to the given server and download the required jars.
|
|
It will then unpack the JAR to a temporary folder and reference those files in further
|
|
contract processing.</p><p>Example:</p><pre class="programlisting">@AutoConfigureStubRunner(repositoryRoot=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://foo.bar"</span>, ids = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example:beer-api-producer:+:stubs:8095"</span>)</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_classpath_scanning" href="#_classpath_scanning"></a>Classpath scanning</h4></div></div></div><p>If you <span class="strong"><strong>DON’T</strong></span> provide the <code class="literal">stubrunner.repositoryRoot</code> and <code class="literal">stubrunner.workOffline</code> flag will
|
|
be set to <code class="literal">false</code> (that’s the default) then classpath will get scanned. Let’s look at the
|
|
following example:</p><pre class="programlisting">@AutoConfigureStubRunner(ids = {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example:beer-api-producer:+:stubs:8095"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example.foo:bar:1.0.0:superstubs:8096"</span>
|
|
})</pre><p>If you’ve added the dependencies to your classpath</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>com.example<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>beer-api-producer-restdocs<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><classifier></span>stubs<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></classifier></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>0.0.1-SNAPSHOT<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>com.example.foo<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>bar<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><classifier></span>superstubs<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></classifier></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>1.0.0<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusion></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></exclusions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">testCompile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example:beer-api-producer-restdocs:0.0.1-SNAPSHOT:stubs"</span>) {
|
|
transitive = false
|
|
}
|
|
testCompile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example.foo:bar:1.0.0:superstubs"</span>) {
|
|
transitive = false
|
|
}</pre><p class="secondary">
|
|
</p><p>Then the following locations on your classpath will get scanned. For <code class="literal">com.example:beer-api-producer-restdocs</code></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">/META-INF/com.example/beer-api-producer-restdocs/<span class="strong"><strong>*/</strong></span>.*</li><li class="listitem">/contracts/com.example/beer-api-producer-restdocs/<span class="strong"><strong>*/</strong></span>.*</li><li class="listitem">/mappings/com.example/beer-api-producer-restdocs/<span class="strong"><strong>*/</strong></span>.*</li></ul></div><p>and <code class="literal">com.example.foo:bar</code></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">/META-INF/com.example.foo/bar/<span class="strong"><strong>*/</strong></span>.*</li><li class="listitem">/contracts/com.example.foo/bar/<span class="strong"><strong>*/</strong></span>.*</li><li class="listitem">/mappings/com.example.foo/bar/<span class="strong"><strong>*/</strong></span>.*</li></ul></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>As you can see you have to explicitly provide the group and artifact ids when packaging the
|
|
producer stubs.</p></td></tr></table></div><p>The producer would setup the contracts like this:</p><pre class="programlisting">└── src
|
|
└── <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>
|
|
└── resources
|
|
└── contracts
|
|
└── com.example
|
|
└── beer-api-producer-restdocs
|
|
└── nested
|
|
└── contract3.groovy</pre><p>To achieve proper stub packaging.</p><p>Or using the <a class="link" href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/master/producer_with_restdocs/pom.xml" target="_top">Maven <code class="literal">assembly</code> plugin</a> or
|
|
<a class="link" href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/master/producer_with_restdocs/build.gradle" target="_top">Gradle Jar</a> task you have to create the following
|
|
structure in your stubs jar.</p><pre class="programlisting">└── META-INF
|
|
└── com.example
|
|
└── beer-api-producer-restdocs
|
|
└── <span class="hl-number">2.0</span>.<span class="hl-number">0</span>
|
|
├── contracts
|
|
│ └── nested
|
|
│ └── contract2.groovy
|
|
└── mappings
|
|
└── mapping.json</pre><p>By maintaining this structure classpath gets scanned and you can profit from the messaging /
|
|
HTTP stubs without the need to download artifacts.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_running_stubs" href="#_running_stubs"></a>82.3.2 Running stubs</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_limitations" href="#_limitations"></a>Limitations</h4></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>There might be a problem with StubRunner shutting down ports between tests. You might
|
|
have a situation in which you get port conflicts. As long as you use the same context across tests
|
|
everything works fine. But when the context are different (e.g. different stubs or different profiles)
|
|
then you have to either use <code class="literal">@DirtiesContext</code> to shut down the stub servers, or else run them on
|
|
different ports per test.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_running_using_main_app" href="#_running_using_main_app"></a>Running using main app</h4></div></div></div><p>You can set the following options to the main class:</p><pre class="programlisting">-c, --classifier Suffix <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> the jar containing stubs (e.
|
|
g. <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'stubs'</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> the stub jar would
|
|
have a <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'stubs'</span> classifier <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> stubs:
|
|
foobar-stubs ). Defaults to <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'stubs'</span>
|
|
(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">default</span>: stubs)
|
|
--maxPort, --maxp <Integer> Maximum port value to be assigned to
|
|
the WireMock instance. Defaults to
|
|
<span class="hl-number">15000</span> (<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">default</span>: <span class="hl-number">15000</span>)
|
|
--minPort, --minp <Integer> Minimum port value to be assigned to
|
|
the WireMock instance. Defaults to
|
|
<span class="hl-number">10000</span> (<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">default</span>: <span class="hl-number">10000</span>)
|
|
-p, --password Password to user when connecting to
|
|
repository
|
|
--phost, --proxyHost Proxy host to use <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> repository
|
|
requests
|
|
--pport, --proxyPort [Integer] Proxy port to use <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> repository
|
|
requests
|
|
-r, --root Location of a Jar containing server
|
|
where you keep your stubs (e.g. http:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//nexus.</span>
|
|
net/content/repositories/repository)
|
|
-s, --stubs Comma separated list of Ivy
|
|
representation of jars with stubs.
|
|
Eg. groupid:artifactid1,groupid2:
|
|
artifactid2:classifier
|
|
-u, --username Username to user when connecting to
|
|
repository
|
|
--wo, --workOffline Switch to work offline. Defaults to
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'false'</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_http_stubs" href="#_http_stubs"></a>HTTP Stubs</h4></div></div></div><p>Stubs are defined in JSON documents, whose syntax is defined in <a class="link" href="http://wiremock.org/stubbing.html" target="_top">WireMock documentation</a></p><p>Example:</p><pre class="programlisting">{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"GET"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/ping"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span>: <span class="hl-number">200</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"pong"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"text/plain"</span>
|
|
}
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_viewing_registered_mappings" href="#_viewing_registered_mappings"></a>Viewing registered mappings</h4></div></div></div><p>Every stubbed collaborator exposes list of defined mappings under <code class="literal">__/admin/</code> endpoint.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_messaging_stubs" href="#_messaging_stubs"></a>Messaging Stubs</h4></div></div></div><p>Depending on the provided Stub Runner dependency and the DSL the messaging routes are automatically set up.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_junit_rule" href="#_stub_runner_junit_rule"></a>82.4 Stub Runner JUnit Rule</h2></div></div></div><p>Stub Runner comes with a JUnit rule thanks to which you can very easily download and run stubs for given group and artifact id:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ClassRule</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> StubRunnerRule rule = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> StubRunnerRule()
|
|
.repoRoot(repoRoot())
|
|
.downloadStub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)
|
|
.downloadStub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer"</span>);</pre><p>After that rule gets executed Stub Runner connects to your Maven repository and for the given list of dependencies tries to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">download them</li><li class="listitem">cache them locally</li><li class="listitem">unzip them to a temporary folder</li><li class="listitem">start a WireMock server for each Maven dependency on a random port from the provided range of ports / provided port</li><li class="listitem">feed the WireMock server with all JSON files that are valid WireMock definitions</li><li class="listitem">can also send messages (remember to pass an implementation of <code class="literal">MessageVerifier</code> interface)</li></ul></div><p>Stub Runner uses <a class="link" href="https://wiki.eclipse.org/Aether" target="_top">Eclipse Aether</a> mechanism to download the Maven dependencies.
|
|
Check their <a class="link" href="https://wiki.eclipse.org/Aether" target="_top">docs</a> for more information.</p><p>Since the <code class="literal">StubRunnerRule</code> implements the <code class="literal">StubFinder</code> it allows you to find the started stubs:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.stubrunner;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> java.net.URL;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> java.util.Collection;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> java.util.Map;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.Contract;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> StubFinder <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> StubTrigger {
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* For the given groupId and artifactId tries to find the matching
|
|
* URL of the running stub.
|
|
*
|
|
* @param groupId - might be null. In that case a search only via artifactId takes place
|
|
* @return URL of a running stub or throws exception if not found
|
|
*/</strong>
|
|
URL findStubUrl(String groupId, String artifactId) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> StubNotFoundException;
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* For the given Ivy notation {@code [groupId]:artifactId:[version]:[classifier]} tries to
|
|
* find the matching URL of the running stub. You can also pass only {@code artifactId}.
|
|
*
|
|
* @param ivyNotation - Ivy representation of the Maven artifact
|
|
* @return URL of a running stub or throws exception if not found
|
|
*/</strong>
|
|
URL findStubUrl(String ivyNotation) <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> StubNotFoundException;
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Returns all running stubs
|
|
*/</strong>
|
|
RunningStubs findAllRunningStubs();
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Returns the list of Contracts
|
|
*/</strong>
|
|
Map<StubConfiguration, Collection<Contract>> getContracts();
|
|
}</pre><p>Example of usage in Spock tests:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ClassRule</span></em> <em><span class="hl-annotation" style="color: gray">@Shared</span></em> StubRunnerRule rule = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> StubRunnerRule()
|
|
.repoRoot(StubRunnerRuleSpec.getResource(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/m2repo/repository"</span>).toURI().toString())
|
|
.downloadStub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)
|
|
.downloadStub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer"</span>)
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should start WireMock servers'</span>() {
|
|
expect: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'WireMocks are running'</span>
|
|
rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>) != null
|
|
rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>) != null
|
|
rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>) == rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>)
|
|
rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer'</span>) != null
|
|
and:
|
|
rule.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>)
|
|
rule.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'fraudDetectionServer'</span>)
|
|
rule.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer'</span>)
|
|
and: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Stubs were registered'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${rule.findStubUrl('loanIssuance').toString()}/name"</span>.toURL().text == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${rule.findStubUrl('fraudDetectionServer').toString()}/name"</span>.toURL().text == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'fraudDetectionServer'</span>
|
|
}</pre><p>Example of usage in JUnit tests:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> should_start_wiremock_servers() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// expect: 'WireMocks are running'</span>
|
|
then(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)).isNotNull();
|
|
then(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)).isNotNull();
|
|
then(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)).isEqualTo(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>));
|
|
then(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer"</span>)).isNotNull();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
then(rule.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)).isTrue();
|
|
then(rule.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fraudDetectionServer"</span>)).isTrue();
|
|
then(rule.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer"</span>)).isTrue();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and: 'Stubs were registered'</span>
|
|
then(httpGet(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>).toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/name"</span>)).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>);
|
|
then(httpGet(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fraudDetectionServer"</span>).toString() + <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/name"</span>)).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fraudDetectionServer"</span>);
|
|
}</pre><p>Check the <span class="strong"><strong>Common properties for JUnit and Spring</strong></span> for more information on how to apply global configuration of Stub Runner.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>To use the JUnit rule together with messaging you have to provide an implementation of the
|
|
<code class="literal">MessageVerifier</code> interface to the rule builder (e.g. <code class="literal">rule.messageVerifier(new MyMessageVerifier())</code>).
|
|
If you don’t do this then whenever you try to send a message an exception will be thrown.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_maven_settings" href="#_maven_settings"></a>82.4.1 Maven settings</h3></div></div></div><p>The stub downloader honors Maven settings for a different local repository folder.
|
|
Authentication details for repositories and profiles are currently not taken into account, so you need to specify it using the properties mentioned above.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_providing_fixed_ports" href="#_providing_fixed_ports"></a>82.4.2 Providing fixed ports</h3></div></div></div><p>You can also run your stubs on fixed ports. You can do it in two different ways. One is to pass it in the properties, and the other via fluent API of
|
|
JUnit rule.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_fluent_api" href="#_fluent_api"></a>82.4.3 Fluent API</h3></div></div></div><p>When using the <code class="literal">StubRunnerRule</code> you can add a stub to download and then pass the port for the last downloaded stub.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ClassRule</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> StubRunnerRule rule = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> StubRunnerRule()
|
|
.repoRoot(repoRoot())
|
|
.downloadStub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)
|
|
.withPort(<span class="hl-number">12345</span>)
|
|
.downloadStub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer:12346"</span>);</pre><p>You can see that for this example the following test is valid:</p><pre class="programlisting">then(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>)).isEqualTo(URI.create(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://localhost:12345"</span>).toURL());
|
|
then(rule.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fraudDetectionServer"</span>)).isEqualTo(URI.create(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://localhost:12346"</span>).toURL());</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_stub_runner_with_spring" href="#_stub_runner_with_spring"></a>82.4.4 Stub Runner with Spring</h3></div></div></div><p>Sets up Spring configuration of the Stub Runner project.</p><p>By providing a list of stubs inside your configuration file the Stub Runner automatically downloads
|
|
and registers in WireMock the selected stubs.</p><p>If you want to find the URL of your stubbed dependency you can autowire the <code class="literal">StubFinder</code> interface and use
|
|
its methods as presented below:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ContextConfiguration(classes = Config, loader = SpringBootContextLoader)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(properties = [" stubrunner.cloud.enabled=false",
|
|
"stubrunner.camel.enabled=false",
|
|
'foo=${stubrunner.runningstubs.fraudDetectionServer.port}'])</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@DirtiesContext</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ActiveProfiles("test")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> StubRunnerConfigurationSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> StubFinder stubFinder
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> Environment environment
|
|
<em><span class="hl-annotation" style="color: gray">@Value('${foo}')</span></em> Integer foo
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@BeforeClass</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AfterClass</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> setupProps() {
|
|
System.clearProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stubrunner.repository.root"</span>)
|
|
System.clearProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stubrunner.classifier"</span>)
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should start WireMock servers'</span>() {
|
|
expect: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'WireMocks are running'</span>
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>) != null
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>) != null
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>) == stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>)
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>) == stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:loanIssuance'</span>)
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:loanIssuance:0.0.1-SNAPSHOT'</span>) == stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:loanIssuance:0.0.1-SNAPSHOT:stubs'</span>)
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer'</span>) != null
|
|
and:
|
|
stubFinder.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>)
|
|
stubFinder.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'fraudDetectionServer'</span>)
|
|
stubFinder.findAllRunningStubs().isPresent(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer'</span>)
|
|
and: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Stubs were registered'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${stubFinder.findStubUrl('loanIssuance').toString()}/name"</span>.toURL().text == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${stubFinder.findStubUrl('fraudDetectionServer').toString()}/name"</span>.toURL().text == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'fraudDetectionServer'</span>
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should throw an exception when stub is not found'</span>() {
|
|
when:
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'nonExistingService'</span>)
|
|
then:
|
|
thrown(StubNotFoundException)
|
|
when:
|
|
stubFinder.findStubUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'nonExistingGroupId'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'nonExistingArtifactId'</span>)
|
|
then:
|
|
thrown(StubNotFoundException)
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should register started servers as environment variables'</span>() {
|
|
expect:
|
|
environment.getProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stubrunner.runningstubs.loanIssuance.port"</span>) != null
|
|
stubFinder.findAllRunningStubs().getPort(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanIssuance"</span>) == (environment.getProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stubrunner.runningstubs.loanIssuance.port"</span>) as Integer)
|
|
and:
|
|
environment.getProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stubrunner.runningstubs.fraudDetectionServer.port"</span>) != null
|
|
stubFinder.findAllRunningStubs().getPort(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fraudDetectionServer"</span>) == (environment.getProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"stubrunner.runningstubs.fraudDetectionServer.port"</span>) as Integer)
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should be able to interpolate a running stub in the passed test property'</span>() {
|
|
given:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> fraudPort = stubFinder.findAllRunningStubs().getPort(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fraudDetectionServer"</span>)
|
|
expect:
|
|
fraudPort > <span class="hl-number">0</span>
|
|
environment.getProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>, Integer) == fraudPort
|
|
foo == fraudPort
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Configuration</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableAutoConfiguration</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Config {}
|
|
}</pre><p>for the following configuration file:</p><pre class="programlisting">stubrunner:
|
|
repositoryRoot: classpath:m2repo/repository/
|
|
ids:
|
|
- org.springframework.cloud.contract.verifier.stubs:loanIssuance
|
|
- org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer
|
|
- org.springframework.cloud.contract.verifier.stubs:bootService
|
|
cloud:
|
|
enabled: false
|
|
camel:
|
|
enabled: false
|
|
|
|
spring.cloud:
|
|
consul.enabled: false
|
|
service-registry.enabled: false</pre><p>Instead of using the properties you can also use the properties inside the <code class="literal">@AutoConfigureStubRunner</code>.
|
|
Below you can find an example of achieving the same result by setting values on the annotation.</p><pre class="programlisting">@AutoConfigureStubRunner(
|
|
ids = [<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:loanIssuance"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:bootService"</span>],
|
|
repositoryRoot = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"classpath:m2repo/repository/"</span>)</pre><p>Stub Runner Spring registers environment variables in the following manner
|
|
for every registered WireMock server. Example for Stub Runner ids
|
|
<code class="literal">com.example:foo</code>, <code class="literal">com.example:bar</code>.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">stubrunner.runningstubs.foo.port</code></li><li class="listitem"><code class="literal">stubrunner.runningstubs.bar.port</code></li></ul></div><p>Which you can reference in your code.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_spring_cloud" href="#_stub_runner_spring_cloud"></a>82.5 Stub Runner Spring Cloud</h2></div></div></div><p>Stub Runner can integrate with Spring Cloud.</p><p>For real life examples you can check the</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/master/producer" target="_top">producer app sample</a></li><li class="listitem"><a class="link" href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/master/consumer_with_discovery" target="_top">consumer app sample</a></li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_stubbing_service_discovery" href="#_stubbing_service_discovery"></a>82.5.1 Stubbing Service Discovery</h3></div></div></div><p>The most important feature of <code class="literal">Stub Runner Spring Cloud</code> is the fact that it’s stubbing</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">DiscoveryClient</code></li><li class="listitem"><code class="literal">Ribbon</code> <code class="literal">ServerList</code></li></ul></div><p>that means that regardless of the fact whether you’re using Zookeeper, Consul, Eureka or anything else, you don’t need that in your tests.
|
|
We’re starting WireMock instances of your dependencies and we’re telling your application whenever you’re using <code class="literal">Feign</code>, load balanced <code class="literal">RestTemplate</code>
|
|
or <code class="literal">DiscoveryClient</code> directly, to call those stubbed servers instead of calling the real Service Discovery tool.</p><p>For example this test will pass</p><pre class="programlisting">def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should make service discovery work'</span>() {
|
|
expect: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'WireMocks are running'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${stubFinder.findStubUrl('loanIssuance').toString()}/name"</span>.toURL().text == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${stubFinder.findStubUrl('fraudDetectionServer').toString()}/name"</span>.toURL().text == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'fraudDetectionServer'</span>
|
|
and: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Stubs can be reached via load service discovery'</span>
|
|
restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'http://loanIssuance/name'</span>, String) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loanIssuance'</span>
|
|
restTemplate.getForObject(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'http://someNameThatShouldMapFraudDetectionServer/name'</span>, String) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'fraudDetectionServer'</span>
|
|
}</pre><p>for the following configuration file</p><pre class="programlisting">spring.cloud:
|
|
zookeeper.enabled: false
|
|
consul.enabled: false
|
|
eureka.client.enabled: false
|
|
stubrunner:
|
|
camel.enabled: false
|
|
idsToServiceIds:
|
|
ivyNotation: someValueInsideYourCode
|
|
fraudDetectionServer: someNameThatShouldMapFraudDetectionServer</pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_test_profiles_and_service_discovery" href="#_test_profiles_and_service_discovery"></a>Test profiles and service discovery</h4></div></div></div><p>In your integration tests you typically don’t want to call neither a discovery service (e.g. Eureka)
|
|
or Config Server. That’s why you create an additional test configuration in which you want to disable
|
|
these features.</p><p>Due to certain limitations of <a class="link" href="https://github.com/spring-cloud/spring-cloud-commons/issues/156" target="_top"><code class="literal">spring-cloud-commons</code></a> to achieve this you have disable these properties
|
|
via a static block like presented below (example for Eureka)</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//Hack to work around https://github.com/spring-cloud/spring-cloud-commons/issues/156</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> {
|
|
System.setProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"eureka.client.enabled"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"false"</span>);
|
|
System.setProperty(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"spring.cloud.config.failFast"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"false"</span>);
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_additional_configuration" href="#_additional_configuration"></a>82.5.2 Additional Configuration</h3></div></div></div><p>You can match the artifactId of the stub with the name of your app by using the <code class="literal">stubrunner.idsToServiceIds:</code> map.
|
|
You can disable Stub Runner Ribbon support by providing: <code class="literal">stubrunner.cloud.ribbon.enabled</code> equal to <code class="literal">false</code>
|
|
You can disable Stub Runner support by providing: <code class="literal">stubrunner.cloud.enabled</code> equal to <code class="literal">false</code></p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>By default all service discovery will be stubbed. That means that regardless of the fact if you have
|
|
an existing <code class="literal">DiscoveryClient</code> its results will be ignored. However, if you want to reuse it, just set
|
|
<code class="literal">stubrunner.cloud.delegate.enabled</code> to <code class="literal">true</code> and then your existing <code class="literal">DiscoveryClient</code> results will be
|
|
merged with the stubbed ones.</p></td></tr></table></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_boot_application" href="#_stub_runner_boot_application"></a>82.6 Stub Runner Boot Application</h2></div></div></div><p>Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to
|
|
trigger the messaging labels and to access started WireMock servers.</p><p>One of the use-cases is to run some smoke (end to end) tests on a deployed application.
|
|
You can check out the <a class="link" href="https://github.com/spring-cloud/spring-cloud-pipelines" target="_top">Spring Cloud Pipelines</a>
|
|
project for more information.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_how_to_use_it" href="#_how_to_use_it"></a>82.6.1 How to use it?</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_stub_runner_server" href="#_stub_runner_server"></a>Stub Runner Server</h4></div></div></div><p>Just add the</p><pre class="programlisting">compile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-starter-stub-runner"</span></pre><p>Annotate a class with <code class="literal">@EnableStubRunnerServer</code>, build a fat-jar and you’re ready to go!</p><p>For the properties check the <span class="strong"><strong>Stub Runner Spring</strong></span> section.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_spring_cloud_cli" href="#_spring_cloud_cli"></a>Spring Cloud CLI</h4></div></div></div><p>Starting from <code class="literal">1.4.0.RELEASE</code> version of the <a class="link" href="http://cloud.spring.io/spring-cloud-cli" target="_top">Spring Cloud CLI</a>
|
|
project you can start Stub Runner Boot by executing <code class="literal">spring cloud stubrunner</code>.</p><p>In order to pass the configuration just create a <code class="literal">stubrunner.yml</code> file in the current working directory
|
|
or a subdirectory called <code class="literal">config</code> or in <code class="literal">~/.spring-cloud</code>. The file could look like this
|
|
(example for running stubs installed locally)</p><p><b>stubrunner.yml. </b>
|
|
</p><pre class="programlisting">stubrunner:
|
|
workOffline: true
|
|
ids:
|
|
- com.example:beer-api-producer:+:9876</pre><p>
|
|
</p><p>and then just call <code class="literal">spring cloud stubrunner</code> from your terminal window to start
|
|
the Stub Runner server. It will be available at port <code class="literal">8750</code>.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_endpoints_2" href="#_endpoints_2"></a>82.6.2 Endpoints</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_http_2" href="#_http_2"></a>HTTP</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">GET <code class="literal">/stubs</code> - returns a list of all running stubs in <code class="literal">ivy:integer</code> notation</li><li class="listitem">GET <code class="literal">/stubs/{ivy}</code> - returns a port for the given <code class="literal">ivy</code> notation (when calling the endpoint <code class="literal">ivy</code> can also be <code class="literal">artifactId</code> only)</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_messaging_2" href="#_messaging_2"></a>Messaging</h4></div></div></div><p>For Messaging</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">GET <code class="literal">/triggers</code> - returns a list of all running labels in <code class="literal">ivy : [ label1, label2 …​]</code> notation</li><li class="listitem">POST <code class="literal">/triggers/{label}</code> - executes a trigger with <code class="literal">label</code></li><li class="listitem">POST <code class="literal">/triggers/{ivy}/{label}</code> - executes a trigger with <code class="literal">label</code> for the given <code class="literal">ivy</code> notation (when calling the endpoint <code class="literal">ivy</code> can also be <code class="literal">artifactId</code> only)</li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_example_2" href="#_example_2"></a>82.6.3 Example</h3></div></div></div><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ContextConfiguration(classes = StubRunnerBoot, loader = SpringBootContextLoader)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(properties = "spring.cloud.zookeeper.enabled=false")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@ActiveProfiles("test")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> StubRunnerBootSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> StubRunning stubRunning
|
|
|
|
def setup() {
|
|
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpStubsController(stubRunning),
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TriggerController(stubRunning))
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should return a list of running stub servers in "full ivy:port" notation'</span>() {
|
|
when:
|
|
String response = RestAssuredMockMvc.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/stubs'</span>).body.asString()
|
|
then:
|
|
def root = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> JsonSlurper().parseText(response)
|
|
root.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs'</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">instanceof</span> Integer
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should return a port on which a [#stubId] stub is running'</span>() {
|
|
when:
|
|
def response = RestAssuredMockMvc.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/stubs/${stubId}"</span>)
|
|
then:
|
|
response.statusCode == <span class="hl-number">200</span>
|
|
response.body.as(Integer) > <span class="hl-number">0</span>
|
|
where:
|
|
stubId << [<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService:+:stubs'</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs'</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService:+'</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService'</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bootService'</span>]
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should return 404 when missing stub was called'</span>() {
|
|
when:
|
|
def response = RestAssuredMockMvc.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/stubs/a:b:c:d"</span>)
|
|
then:
|
|
response.statusCode == <span class="hl-number">404</span>
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should return a list of messaging labels that can be triggered when version and classifier are passed'</span>() {
|
|
when:
|
|
String response = RestAssuredMockMvc.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/triggers'</span>).body.asString()
|
|
then:
|
|
def root = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> JsonSlurper().parseText(response)
|
|
root.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs'</span>?.containsAll([<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"delete_book"</span>,<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"return_book_1"</span>,<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"return_book_2"</span>])
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should trigger a messaging label'</span>() {
|
|
given:
|
|
StubRunning stubRunning = Mock()
|
|
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpStubsController(stubRunning), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TriggerController(stubRunning))
|
|
when:
|
|
def response = RestAssuredMockMvc.post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/triggers/delete_book"</span>)
|
|
then:
|
|
response.statusCode == <span class="hl-number">200</span>
|
|
and:
|
|
<span class="hl-number">1</span> * stubRunning.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'delete_book'</span>)
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should trigger a messaging label for a stub with [#stubId] ivy notation'</span>() {
|
|
given:
|
|
StubRunning stubRunning = Mock()
|
|
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> HttpStubsController(stubRunning), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> TriggerController(stubRunning))
|
|
when:
|
|
def response = RestAssuredMockMvc.post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/triggers/$stubId/delete_book"</span>)
|
|
then:
|
|
response.statusCode == <span class="hl-number">200</span>
|
|
and:
|
|
<span class="hl-number">1</span> * stubRunning.trigger(stubId, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'delete_book'</span>)
|
|
where:
|
|
stubId << [<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService:stubs'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:bootService'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bootService'</span>]
|
|
}
|
|
|
|
def <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'should throw exception when trigger is missing'</span>() {
|
|
when:
|
|
RestAssuredMockMvc.post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/triggers/missing_label"</span>)
|
|
then:
|
|
Exception e = thrown(Exception)
|
|
e.message.contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Exception occurred while trying to return [missing_label] label."</span>)
|
|
e.message.contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Available labels are"</span>)
|
|
e.message.contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:loanIssuance:0.0.1-SNAPSHOT:stubs=[]"</span>)
|
|
e.message.contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs="</span>)
|
|
}
|
|
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_stub_runner_boot_with_service_discovery" href="#_stub_runner_boot_with_service_discovery"></a>82.6.4 Stub Runner Boot with Service Discovery</h3></div></div></div><p>One of the possibilities of using Stub Runner Boot is to use it as a feed of stubs for "smoke-tests". What does it mean?
|
|
Let’s assume that you don’t want to deploy 50 microservice to a test environment in order
|
|
to check if your application is working fine. You’ve already executed a suite of tests during the build process
|
|
but you would also like to ensure that the packaging of your application is fine. What you can do
|
|
is to deploy your application to an environment, start it and run a couple of tests on it to see if
|
|
it’s working fine. We can call those tests smoke-tests since their idea is to check only a handful
|
|
of testing scenarios.</p><p>The problem with this approach is such that if you’re doing microservices most likely you’re
|
|
using a service discovery tool. Stub Runner Boot allows you to solve this issue by starting the
|
|
required stubs and register them in a service discovery tool. Let’s take a look at an example of
|
|
such a setup with Eureka. Let’s assume that Eureka was already running.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableStubRunnerServer</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@EnableEurekaClient</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> StubRunnerBootEurekaExample {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(StubRunnerBootEurekaExample.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
|
|
}</pre><p>As you can see we want to start a Stub Runner Boot server <code class="literal">@EnableStubRunnerServer</code>, enable Eureka client <code class="literal">@EnableEurekaClient</code>
|
|
and we want to have the stub runner feature turned on <code class="literal">@AutoConfigureStubRunner</code>.</p><p>Now let’s assume that we want to start this application so that the stubs get automatically registered.
|
|
We can do it by running the app <code class="literal">java -jar ${SYSTEM_PROPS} stub-runner-boot-eureka-example.jar</code> where
|
|
<code class="literal">${SYSTEM_PROPS}</code> would contain the following list of properties</p><pre class="programlisting">-Dstubrunner.repositoryRoot=http://repo.spring.io/snapshots (<span class="hl-number">1</span>)
|
|
-Dstubrunner.cloud.stubbed.discovery.enabled=false (<span class="hl-number">2</span>)
|
|
-Dstubrunner.ids=org.springframework.cloud.contract.verifier.stubs:loanIssuance,org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer,org.springframework.cloud.contract.verifier.stubs:bootService (<span class="hl-number">3</span>)
|
|
-Dstubrunner.idsToServiceIds.fraudDetectionServer=someNameThatShouldMapFraudDetectionServer (<span class="hl-number">4</span>)
|
|
|
|
(<span class="hl-number">1</span>) - we tell Stub Runner where all the stubs reside
|
|
(<span class="hl-number">2</span>) - we don<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'t want the default behaviour where the discovery service is stubbed. That'</span>s why the stub registration will be picked
|
|
(<span class="hl-number">3</span>) - we provide a list of stubs to download
|
|
(<span class="hl-number">4</span>) - we provide a list of artifactId to serviceId mapping</pre><p>That way your deployed application can send requests to started WireMock servers via the service
|
|
discovery. Most likely points 1-3 could be set by default in <code class="literal">application.yml</code> cause they are not
|
|
likely to change. That way you can provide only the list of stubs to download whenever you start
|
|
the Stub Runner Boot.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stubs_per_consumer" href="#_stubs_per_consumer"></a>82.7 Stubs Per Consumer</h2></div></div></div><p>There are cases in which 2 consumers of the same endpoint want to have 2 different responses.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>This approach also allows you to immediately know which consumer is using which part of your API.
|
|
You can remove part of a response that your API produces and you can see which of your autogenerated tests
|
|
fails. If none fails then you can safely delete that part of the response cause nobody is using it.</p></td></tr></table></div><p>Let’s look at the following example for contract defined for the producer called <code class="literal">producer</code>.
|
|
There are 2 consumers: <code class="literal">foo-consumer</code> and <code class="literal">bar-consumer</code>.</p><p><span class="strong"><strong>Consumer <code class="literal">foo-service</code></strong></span></p><pre class="programlisting">request {
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/foo'</span>
|
|
method GET()
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body(
|
|
foo: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>
|
|
}
|
|
}</pre><p><span class="strong"><strong>Consumer <code class="literal">bar-service</code></strong></span></p><pre class="programlisting">request {
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/foo'</span>
|
|
method GET()
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body(
|
|
bar: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>
|
|
}
|
|
}</pre><p>You can’t produce for the same request 2 different responses. That’s why you can properly package the
|
|
contracts and then profit from the <code class="literal">stubsPerConsumer</code> feature.</p><p>On the producer side the consumers can have a folder that contains contracts related only to them.
|
|
By setting the <code class="literal">stubrunner.stubs-per-consumer</code> flag to <code class="literal">true</code> we no longer register all stubs but only those that
|
|
correspond to the consumer application’s name. In other words we’ll scan the path of every stub and
|
|
if it contains the subfolder with name of the consumer in the path only then will it get registered.</p><p>On the <code class="literal">foo</code> producer side the contracts would look like this</p><pre class="programlisting">.
|
|
└── contracts
|
|
├── bar-consumer
|
|
│ ├── bookReturnedForBar.groovy
|
|
│ └── shouldCallBar.groovy
|
|
└── foo-consumer
|
|
├── bookReturnedForFoo.groovy
|
|
└── shouldCallFoo.groovy</pre><p>Being the <code class="literal">bar-consumer</code> consumer you can either set the <code class="literal">spring.application.name</code> or the <code class="literal">stubrunner.consumer-name</code> to <code class="literal">bar-consumer</code>
|
|
Or set the test as follows:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ContextConfiguration(classes = Config, loader = SpringBootContextLoader)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(properties = ["spring.application.name=bar-consumer"])</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner(ids = "org.springframework.cloud.contract.verifier.stubs:producerWithMultipleConsumers",
|
|
repositoryRoot = "classpath:m2repo/repository/",
|
|
stubsPerConsumer = true)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@DirtiesContext</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> StubRunnerStubsPerConsumerSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
...
|
|
}</pre><p>Then only the stubs registered under a path that contains the <code class="literal">bar-consumer</code> in its name (i.e. those from the
|
|
<code class="literal">src/test/resources/contracts/bar-consumer/some/contracts/…​</code> folder) will be allowed to be referenced.</p><p>Or set the consumer name explicitly</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ContextConfiguration(classes = Config, loader = SpringBootContextLoader)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner(ids = "org.springframework.cloud.contract.verifier.stubs:producerWithMultipleConsumers",
|
|
repositoryRoot = "classpath:m2repo/repository/",
|
|
consumerName = "foo-consumer",
|
|
stubsPerConsumer = true)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@DirtiesContext</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> StubRunnerStubsPerConsumerWithConsumerNameSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
...
|
|
}</pre><p>Then only the stubs registered under a path that contains the <code class="literal">foo-consumer</code> in its name (i.e. those from the
|
|
<code class="literal">src/test/resources/contracts/foo-consumer/some/contracts/…​</code> folder) will be allowed to be referenced.</p><p>You can check out <a class="link" href="https://github.com/spring-cloud/spring-cloud-contract/issues/224" target="_top">issue 224</a> for more
|
|
information about the reasons behind this change.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_common" href="#_common"></a>82.8 Common</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_common_properties_for_junit_and_spring" href="#_common_properties_for_junit_and_spring"></a>82.8.1 Common properties for JUnit and Spring</h3></div></div></div><p>Some of the properties that are repetitive can be set using system properties or configuration properties (for Spring). Here are their names with their default values:</p><div class="informaltable"><table style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"><col class="col_3"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Property name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Default value</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Description</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.minPort</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Minimal value of a port for a started WireMock with stubs</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.maxPort</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>15000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Minimal value of a port for a started WireMock with stubs</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.repositoryRoot</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Maven repo url. If blank then will call the local maven repo</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.classifier</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubs</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Default classifier for the stub artifacts</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.workOffline</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>If true then will not contact any remote repositories to download stubs</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.ids</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Array of Ivy notation stubs to download</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.username</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Optional username to access the tool that stores the JARs with stubs</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Optional password to access the tool that stores the JARs with stubs</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.stubsPerConsumer</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Set to <code class="literal">true</code> if you want to use different stubs per each consumer instead of registering all stubs for every consumer</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>stubrunner.consumerName</p></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"> </td><td style="" align="left" valign="top"><p>If you want to use stubs per consumer and want to override the consumer name just change this value</p></td></tr></tbody></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_stub_runner_stubs_ids" href="#_stub_runner_stubs_ids"></a>82.8.2 Stub runner stubs ids</h3></div></div></div><p>You can provide the stubs to download via the <code class="literal">stubrunner.ids</code> system property. They follow the following pattern:</p><pre class="programlisting">groupId:artifactId:version:classifier:port</pre><p><code class="literal">version</code>, <code class="literal">classifier</code> and <code class="literal">port</code> are optional.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">If you don’t provide the <code class="literal">port</code> then a random one will be picked</li><li class="listitem">If you don’t provide the <code class="literal">classifier</code> then the default one will be taken. (NOTE that you can pass an empty classifier like this <code class="literal">groupId:artifactId:version:</code>)</li><li class="listitem">If you don’t provide the <code class="literal">version</code> then the <code class="literal">+</code> will be passed and the latest one will be downloaded</li></ul></div><p>Where <code class="literal">port</code> means the port of the WireMock server.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Starting from version 1.0.4 as a version you can provide a range of versions that you would like
|
|
the Stub Runner to take into consideration. You can read more about the <a class="link" href="https://wiki.eclipse.org/Aether/New_and_Noteworthy#Version_Ranges" target="_top">Aether versioning ranges here</a>.</p></td></tr></table></div><p>Taken from <a class="link" href="http://download.eclipse.org/aether/aether-core/0.9.0/apidocs/org/eclipse/aether/util/version/GenericVersionScheme.html" target="_top">Aether Docs</a>:</p><div class="blockquote"><blockquote class="blockquote"><p>This scheme accepts versions of any form, interpreting a version as a sequence of numeric and alphabetic segments. The characters '-', '_', and '.' as well as the mere
|
|
transitions from digit to letter and vice versa delimit the version segments. Delimiters are treated as equivalent.</p><p>Numeric segments are compared mathematically, alphabetic segments are compared lexicographically and case-insensitively. However, the following qualifier strings are
|
|
recognized and treated specially: "alpha" = "a" < "beta" = "b" < "milestone" = "m" < "cr" = "rc" < "snapshot" < "final" = "ga" < "sp". All of those well-known qualifiers
|
|
are considered smaller/older than other strings. An empty segment/string is equivalent to 0.</p><p>In addition to the above mentioned qualifiers, the tokens "min" and "max" may be used as final version segment to denote the smallest/greatest version having a given prefix.
|
|
For example, "1.2.min" denotes the smallest version in the 1.2 line, "1.2.max" denotes the greatest version in the 1.2 line. A version range of the form "[M.N.*]" is short for "[M.N.min, M.N.max]".</p><p>Numbers and strings are considered incomparable against each other. Where version segments of different kind would collide, comparison will instead assume that the previous
|
|
segments are padded with trailing 0 or "ga" segments, respectively, until the kind mismatch is resolved, e.g. "1-alpha" = "1.0.0-alpha" < "1.0.1-ga" = "1.0.1".</p></blockquote></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_stub_runner_for_messaging" href="#_stub_runner_for_messaging"></a>83. Stub Runner for Messaging</h2></div></div></div><p>Stub Runner has the functionality to run the published stubs in memory. It can integrate with the following frameworks out of the box</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Spring Integration</li><li class="listitem">Spring Cloud Stream</li><li class="listitem">Apache Camel</li><li class="listitem">Spring AMQP</li></ul></div><p>It also provides points of entry to integrate with any other solution on the market.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you have multiple frameworks on the classpath Stub Runner will need to
|
|
define which one should be used. Let’s assume that you have both AMQP, Spring Cloud Stream and Spring Integration
|
|
on the classpath. Then you need to set <code class="literal">stubrunner.stream.enabled=false</code> and <code class="literal">stubrunner.integration.enabled=false</code>.
|
|
That way the only remaining framework is Spring AMQP.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_triggering" href="#_stub_triggering"></a>83.1 Stub triggering</h2></div></div></div><p>To trigger a message it’s enough to use the <code class="literal">StubTrigger</code> interface:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.stubrunner;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> java.util.Collection;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> java.util.Map;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> StubTrigger {
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Triggers an event by a given label for a given {@code groupid:artifactid} notation. You can use only {@code artifactId} too.
|
|
*
|
|
* Feature related to messaging.
|
|
*
|
|
* @return true - if managed to run a trigger
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> trigger(String ivyNotation, String labelName);
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Triggers an event by a given label.
|
|
*
|
|
* Feature related to messaging.
|
|
*
|
|
* @return true - if managed to run a trigger
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> trigger(String labelName);
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Triggers all possible events.
|
|
*
|
|
* Feature related to messaging.
|
|
*
|
|
* @return true - if managed to run a trigger
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> trigger();
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Returns a mapping of ivy notation of a dependency to all the labels it has.
|
|
*
|
|
* Feature related to messaging.
|
|
*/</strong>
|
|
Map<String, Collection<String>> labels();
|
|
}</pre><p>For convenience the <code class="literal">StubFinder</code> interface extends <code class="literal">StubTrigger</code> so it’s enough to use only one in your tests.</p><p><code class="literal">StubTrigger</code> gives you the following options to trigger a message:</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_trigger_by_label" href="#_trigger_by_label"></a>83.1.1 Trigger by label</h3></div></div></div><pre class="programlisting">stubFinder.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>)</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_trigger_by_group_and_artifact_ids" href="#_trigger_by_group_and_artifact_ids"></a>83.1.2 Trigger by group and artifact ids</h3></div></div></div><pre class="programlisting">stubFinder.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.verifier.stubs:camelService'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>)</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_trigger_by_artifact_ids" href="#_trigger_by_artifact_ids"></a>83.1.3 Trigger by artifact ids</h3></div></div></div><pre class="programlisting">stubFinder.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'camelService'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>)</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_trigger_all_messages" href="#_trigger_all_messages"></a>83.1.4 Trigger all messages</h3></div></div></div><pre class="programlisting">stubFinder.trigger()</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_camel" href="#_stub_runner_camel"></a>83.2 Stub Runner Camel</h2></div></div></div><p>Spring Cloud Contract Verifier Stub Runner’s messaging module gives you an easy way to integrate with Apache Camel.
|
|
For the provided artifacts it will automatically download the stubs and register the required
|
|
routes.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_adding_it_to_the_project" href="#_adding_it_to_the_project"></a>83.2.1 Adding it to the project</h3></div></div></div><p>It’s enough to have both Apache Camel and Spring Cloud Contract Stub Runner on classpath.
|
|
Remember to annotate your test class with <code class="literal">@AutoConfigureStubRunner</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_disabling_the_functionality" href="#_disabling_the_functionality"></a>83.2.2 Disabling the functionality</h3></div></div></div><p>If you need to disable this functionality just pass <code class="literal">stubrunner.camel.enabled=false</code> property.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_examples" href="#_examples"></a>83.2.3 Examples</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_stubs_structure" href="#_stubs_structure"></a>Stubs structure</h4></div></div></div><p>Let us assume that we have the following Maven repository with a deployed stubs for the
|
|
<code class="literal">camelService</code> application.</p><pre class="programlisting">└── .m2
|
|
└── repository
|
|
└── io
|
|
└── codearte
|
|
└── accurest
|
|
└── stubs
|
|
└── camelService
|
|
├── <span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT
|
|
│ ├── camelService-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT.pom
|
|
│ ├── camelService-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar
|
|
│ └── maven-metadata-local.xml
|
|
└── maven-metadata-local.xml</pre><p>And the stubs contain the following structure:</p><pre class="programlisting">├── META-INF
|
|
│ └── MANIFEST.MF
|
|
└── repository
|
|
├── accurest
|
|
│ ├── bookDeleted.groovy
|
|
│ ├── bookReturned1.groovy
|
|
│ └── bookReturned2.groovy
|
|
└── mappings</pre><p>Let’s consider the following contracts (let' number it with <span class="strong"><strong>1</strong></span>):</p><pre class="programlisting">Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>
|
|
input {
|
|
triggeredBy(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookReturnedTriggered()'</span>)
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>)
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{ "bookName" : "foo" }'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
}
|
|
}
|
|
}</pre><p>and number <span class="strong"><strong>2</strong></span></p><pre class="programlisting">Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_2'</span>
|
|
input {
|
|
messageFrom(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:input'</span>)
|
|
messageBody([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
messageHeaders {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>)
|
|
}
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>)
|
|
body([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
}
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_1_no_input_message_2" href="#_scenario_1_no_input_message_2"></a>Scenario 1 (no input message)</h4></div></div></div><p>So as to trigger a message via the <code class="literal">return_book_1</code> label we’ll use the <code class="literal">StubTigger</code> interface as follows</p><pre class="programlisting">stubFinder.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>)</pre><p>Next we’ll want to listen to the output of the message sent to <code class="literal">jms:output</code></p><pre class="programlisting">Exchange receivedMessage = camelContext.createConsumerTemplate().receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>, <span class="hl-number">5000</span>)</pre><p>And the received message would pass the following assertions</p><pre class="programlisting">receivedMessage != null
|
|
assertThatBodyContainsBookNameFoo(receivedMessage.in.body)
|
|
receivedMessage.in.headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_2_output_triggered_by_input_2" href="#_scenario_2_output_triggered_by_input_2"></a>Scenario 2 (output triggered by input)</h4></div></div></div><p>Since the route is set for you it’s enough to just send a message to the <code class="literal">jms:output</code> destination.</p><pre class="programlisting">camelContext.createProducerTemplate().sendBodyAndHeaders(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:input'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BookReturned(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>), [sample: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>])</pre><p>Next we’ll want to listen to the output of the message sent to <code class="literal">jms:output</code></p><pre class="programlisting">Exchange receivedMessage = camelContext.createConsumerTemplate().receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>, <span class="hl-number">5000</span>)</pre><p>And the received message would pass the following assertions</p><pre class="programlisting">receivedMessage != null
|
|
assertThatBodyContainsBookNameFoo(receivedMessage.in.body)
|
|
receivedMessage.in.headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_3_input_with_no_output" href="#_scenario_3_input_with_no_output"></a>Scenario 3 (input with no output)</h4></div></div></div><p>Since the route is set for you it’s enough to just send a message to the <code class="literal">jms:output</code> destination.</p><pre class="programlisting">camelContext.createProducerTemplate().sendBodyAndHeaders(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:delete'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BookReturned(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>), [sample: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>])</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_integration" href="#_stub_runner_integration"></a>83.3 Stub Runner Integration</h2></div></div></div><p>Spring Cloud Contract Verifier Stub Runner’s messaging module gives you an easy way to integrate with Spring Integration.
|
|
For the provided artifacts it will automatically download the stubs and register the required
|
|
routes.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_adding_it_to_the_project_2" href="#_adding_it_to_the_project_2"></a>83.3.1 Adding it to the project</h3></div></div></div><p>It’s enough to have both Spring Integration and Spring Cloud Contract Stub Runner on classpath.
|
|
Remember to annotate your test class with <code class="literal">@AutoConfigureStubRunner</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_disabling_the_functionality_2" href="#_disabling_the_functionality_2"></a>83.3.2 Disabling the functionality</h3></div></div></div><p>If you need to disable this functionality just pass <code class="literal">stubrunner.integration.enabled=false</code> property.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_examples_2" href="#_examples_2"></a>83.3.3 Examples</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_stubs_structure_2" href="#_stubs_structure_2"></a>Stubs structure</h4></div></div></div><p>Let us assume that we have the following Maven repository with a deployed stubs for the
|
|
<code class="literal">integrationService</code> application.</p><pre class="programlisting">└── .m2
|
|
└── repository
|
|
└── io
|
|
└── codearte
|
|
└── accurest
|
|
└── stubs
|
|
└── integrationService
|
|
├── <span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT
|
|
│ ├── integrationService-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT.pom
|
|
│ ├── integrationService-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar
|
|
│ └── maven-metadata-local.xml
|
|
└── maven-metadata-local.xml</pre><p>And the stubs contain the following structure:</p><pre class="programlisting">├── META-INF
|
|
│ └── MANIFEST.MF
|
|
└── repository
|
|
├── accurest
|
|
│ ├── bookDeleted.groovy
|
|
│ ├── bookReturned1.groovy
|
|
│ └── bookReturned2.groovy
|
|
└── mappings</pre><p>Let’s consider the following contracts (let' number it with <span class="strong"><strong>1</strong></span>):</p><pre class="programlisting">Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>
|
|
input {
|
|
triggeredBy(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookReturnedTriggered()'</span>)
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'output'</span>)
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{ "bookName" : "foo" }'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
}
|
|
}
|
|
}</pre><p>and number <span class="strong"><strong>2</strong></span></p><pre class="programlisting">Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_2'</span>
|
|
input {
|
|
messageFrom(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'input'</span>)
|
|
messageBody([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
messageHeaders {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>)
|
|
}
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'output'</span>)
|
|
body([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
}
|
|
}
|
|
}</pre><p>and the following Spring Integration Route:</p><pre class="programlisting"><span class="hl-directive" style="color: maroon"><?xml version="1.0" encoding="UTF-8"?></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><beans:beans</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">xmlns</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"http://www.springframework.org/schema/integration"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">xmlns:xsi</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"http://www.w3.org/2001/XMLSchema-instance"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">xmlns:beans</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"http://www.springframework.org/schema/beans"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">xsi:schemaLocation</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"http://www.springframework.org/schema/beans
|
|
http://www.springframework.org/schema/beans/spring-beans.xsd
|
|
http://www.springframework.org/schema/integration
|
|
http://www.springframework.org/schema/integration/spring-integration.xsd"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- REQUIRED FOR TESTING --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><bridge</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">input-channel</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"output"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">output-channel</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"outputTest"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">/></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><channel</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">id</span>=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-value">"outputTest"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag">></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><queue/></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></channel></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></beans:beans></span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_1_no_input_message_3" href="#_scenario_1_no_input_message_3"></a>Scenario 1 (no input message)</h4></div></div></div><p>So as to trigger a message via the <code class="literal">return_book_1</code> label we’ll use the <code class="literal">StubTigger</code> interface as follows</p><pre class="programlisting">stubFinder.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>)</pre><p>Next we’ll want to listen to the output of the message sent to <code class="literal">output</code></p><pre class="programlisting">Message<?> receivedMessage = messaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'outputTest'</span>)</pre><p>And the received message would pass the following assertions</p><pre class="programlisting">receivedMessage != null
|
|
assertJsons(receivedMessage.payload)
|
|
receivedMessage.headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_2_output_triggered_by_input_3" href="#_scenario_2_output_triggered_by_input_3"></a>Scenario 2 (output triggered by input)</h4></div></div></div><p>Since the route is set for you it’s enough to just send a message to the <code class="literal">output</code> destination.</p><pre class="programlisting">messaging.send(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BookReturned(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>), [sample: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>], <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'input'</span>)</pre><p>Next we’ll want to listen to the output of the message sent to <code class="literal">output</code></p><pre class="programlisting">Message<?> receivedMessage = messaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'outputTest'</span>)</pre><p>And the received message would pass the following assertions</p><pre class="programlisting">receivedMessage != null
|
|
assertJsons(receivedMessage.payload)
|
|
receivedMessage.headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_3_input_with_no_output_2" href="#_scenario_3_input_with_no_output_2"></a>Scenario 3 (input with no output)</h4></div></div></div><p>Since the route is set for you it’s enough to just send a message to the <code class="literal">input</code> destination.</p><pre class="programlisting">messaging.send(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BookReturned(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>), [sample: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>], <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'delete'</span>)</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_stream" href="#_stub_runner_stream"></a>83.4 Stub Runner Stream</h2></div></div></div><p>Spring Cloud Contract Verifier Stub Runner’s messaging module gives you an easy way to integrate with Spring Stream.
|
|
For the provided artifacts it will automatically download the stubs and register the required
|
|
routes.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>In Stub Runner’s integration with Stream the <code class="literal">messageFrom</code> or <code class="literal">sentTo</code> Strings are resolved
|
|
first as a <code class="literal">destination</code> of a channel, and then if there is no such <code class="literal">destination</code> it’s resolved as a
|
|
channel name.</p></td></tr></table></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you want to use Spring Cloud Stream remember to add a
|
|
<code class="literal">org.springframework.cloud:spring-cloud-stream-test-support</code> dependency.</p></td></tr></table></div><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-stream-test-support<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-stream-test-support"</span></pre><p class="secondary">
|
|
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_adding_it_to_the_project_3" href="#_adding_it_to_the_project_3"></a>83.4.1 Adding it to the project</h3></div></div></div><p>It’s enough to have both Spring Cloud Stream and Spring Cloud Contract Stub Runner on classpath.
|
|
Remember to annotate your test class with <code class="literal">@AutoConfigureStubRunner</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_disabling_the_functionality_3" href="#_disabling_the_functionality_3"></a>83.4.2 Disabling the functionality</h3></div></div></div><p>If you need to disable this functionality just pass <code class="literal">stubrunner.stream.enabled=false</code> property.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_examples_3" href="#_examples_3"></a>83.4.3 Examples</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_stubs_structure_3" href="#_stubs_structure_3"></a>Stubs structure</h4></div></div></div><p>Let us assume that we have the following Maven repository with a deployed stubs for the
|
|
<code class="literal">streamService</code> application.</p><pre class="programlisting">└── .m2
|
|
└── repository
|
|
└── io
|
|
└── codearte
|
|
└── accurest
|
|
└── stubs
|
|
└── streamService
|
|
├── <span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT
|
|
│ ├── streamService-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT.pom
|
|
│ ├── streamService-<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT-stubs.jar
|
|
│ └── maven-metadata-local.xml
|
|
└── maven-metadata-local.xml</pre><p>And the stubs contain the following structure:</p><pre class="programlisting">├── META-INF
|
|
│ └── MANIFEST.MF
|
|
└── repository
|
|
├── accurest
|
|
│ ├── bookDeleted.groovy
|
|
│ ├── bookReturned1.groovy
|
|
│ └── bookReturned2.groovy
|
|
└── mappings</pre><p>Let’s consider the following contracts (let' number it with <span class="strong"><strong>1</strong></span>):</p><pre class="programlisting">Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>
|
|
input { triggeredBy(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookReturnedTriggered()'</span>) }
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'returnBook'</span>)
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{ "bookName" : "foo" }'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
headers { header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>) }
|
|
}
|
|
}</pre><p>and number <span class="strong"><strong>2</strong></span></p><pre class="programlisting">Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_2'</span>
|
|
input {
|
|
messageFrom(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookStorage'</span>)
|
|
messageBody([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
messageHeaders { header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>) }
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'returnBook'</span>)
|
|
body([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
headers { header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>) }
|
|
}
|
|
}</pre><p>and the following Spring configuration:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">stubrunner.repositoryRoot</span>: classpath:m2repo/repository/
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">stubrunner.ids</span>: org.springframework.cloud.contract.verifier.stubs:streamService:<span class="hl-number">0.0</span>.<span class="hl-number">1</span>-SNAPSHOT:stubs
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> stream</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> bindings</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> output</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> destination</span>: returnBook
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> input</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> destination</span>: bookStorage
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> port</span>: <span class="hl-number">0</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">debug</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_1_no_input_message_4" href="#_scenario_1_no_input_message_4"></a>Scenario 1 (no input message)</h4></div></div></div><p>So as to trigger a message via the <code class="literal">return_book_1</code> label we’ll use the <code class="literal">StubTrigger</code> interface as follows</p><pre class="programlisting">stubFinder.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'return_book_1'</span>)</pre><p>Next we’ll want to listen to the output of the message sent to a channel whose <code class="literal">destination</code> is <code class="literal">returnBook</code></p><pre class="programlisting">Message<?> receivedMessage = messaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'returnBook'</span>)</pre><p>And the received message would pass the following assertions</p><pre class="programlisting">receivedMessage != null
|
|
assertJsons(receivedMessage.payload)
|
|
receivedMessage.headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_2_output_triggered_by_input_4" href="#_scenario_2_output_triggered_by_input_4"></a>Scenario 2 (output triggered by input)</h4></div></div></div><p>Since the route is set for you it’s enough to just send a message to the <code class="literal">bookStorage</code> <code class="literal">destination</code>.</p><pre class="programlisting">messaging.send(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BookReturned(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>), [sample: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>], <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookStorage'</span>)</pre><p>Next we’ll want to listen to the output of the message sent to <code class="literal">returnBook</code></p><pre class="programlisting">Message<?> receivedMessage = messaging.receive(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'returnBook'</span>)</pre><p>And the received message would pass the following assertions</p><pre class="programlisting">receivedMessage != null
|
|
assertJsons(receivedMessage.payload)
|
|
receivedMessage.headers.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_scenario_3_input_with_no_output_3" href="#_scenario_3_input_with_no_output_3"></a>Scenario 3 (input with no output)</h4></div></div></div><p>Since the route is set for you it’s enough to just send a message to the <code class="literal">output</code> destination.</p><pre class="programlisting">messaging.send(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> BookReturned(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>), [sample: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>], <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'delete'</span>)</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stub_runner_spring_amqp" href="#_stub_runner_spring_amqp"></a>83.5 Stub Runner Spring AMQP</h2></div></div></div><p>Spring Cloud Contract Verifier Stub Runner’s messaging module provides an easy way to integrate with Spring AMQP’s Rabbit Template.
|
|
For the provided artifacts it will automatically download the stubs and register the required
|
|
routes.</p><p>The integration tries to work standalone, that is without interaction with a running RabbitMQ message broker.
|
|
It expects a <code class="literal">RabbitTemplate</code> on the application context and uses it as a spring boot test <code class="literal">@SpyBean</code>.
|
|
Thus it can use the mockito spy functionality to verify and introspect messages sent by the application.</p><p>On the message consumer side, it considers all <code class="literal">@RabbitListener</code> annotated endpoints as well as all `SimpleMessageListenerContainer`s on the application context.</p><p>As messages are usually sent to exchanges in AMQP the message contract contains the exchange name as the destination.
|
|
Message listeners on the other side are bound to queues. Bindings connect an exchange to a queue.
|
|
If message contracts are triggered the Spring AMQP stub runner integration will look for bindings on the application context that match this exchange.
|
|
Then it collects the queues from the Spring exchanges and tries to find messages listeners bound to these queues.
|
|
The message is triggered to all matching message listeners.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_adding_it_to_the_project_4" href="#_adding_it_to_the_project_4"></a>83.5.1 Adding it to the project</h3></div></div></div><p>It’s enough to have both Spring AMQP and Spring Cloud Contract Stub Runner on the classpath and set the property <code class="literal">stubrunner.amqp.enabled=true</code>.
|
|
Remember to annotate your test class with <code class="literal">@AutoConfigureStubRunner</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you already have Stream and Integration on the classpath you need
|
|
to disable them explicitly via <code class="literal">stubrunner.stream.enabled=false</code> and <code class="literal">stubrunner.integration.enabled=false</code>
|
|
properties</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_examples_4" href="#_examples_4"></a>83.5.2 Examples</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_stubs_structure_4" href="#_stubs_structure_4"></a>Stubs structure</h4></div></div></div><p>Let us assume that we have the following Maven repository with a deployed stubs for the
|
|
<code class="literal">spring-cloud-contract-amqp-test</code> application.</p><pre class="programlisting">└── .m2
|
|
└── repository
|
|
└── com
|
|
└── example
|
|
└── spring-cloud-contract-amqp-<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>
|
|
├── <span class="hl-number">0.4</span>.<span class="hl-number">0</span>-SNAPSHOT
|
|
│ ├── spring-cloud-contract-amqp-<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>-<span class="hl-number">0.4</span>.<span class="hl-number">0</span>-SNAPSHOT.pom
|
|
│ ├── spring-cloud-contract-amqp-<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>-<span class="hl-number">0.4</span>.<span class="hl-number">0</span>-SNAPSHOT-stubs.jar
|
|
│ └── maven-metadata-local.xml
|
|
└── maven-metadata-local.xml</pre><p>And the stubs contain the following structure:</p><pre class="programlisting">├── META-INF
|
|
│ └── MANIFEST.MF
|
|
└── contracts
|
|
└── shouldProduceValidPersonData.groovy</pre><p>Let’s consider the following contract:</p><pre class="programlisting">Contract.make {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Human readable description</span>
|
|
description <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Should produce valid person data'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Label by means of which the output message can be triggered</span>
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'contract-test.person.created.event'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// input to the contract</span>
|
|
input {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the contract will be triggered by a method</span>
|
|
triggeredBy(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'createPerson()'</span>)
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// output message of the contract</span>
|
|
outputMessage {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// destination to which the output message will be sent</span>
|
|
sentTo <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'contract-test.exchange'</span>
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'contentType'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>)
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'__TypeId__'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud.contract.stubrunner.messaging.amqp.Person'</span>)
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the body of the output message</span>
|
|
body ([
|
|
id: $(consumer(<span class="hl-number">9</span>), producer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[0-9]+"</span>))),
|
|
name: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"me"</span>
|
|
])
|
|
}
|
|
}</pre><p>and the following Spring configuration:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">stubrunner</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> repositoryRoot</span>: classpath:m2repo/repository/
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ids</span>: org.springframework.cloud.contract.verifier.stubs.amqp:spring-cloud-contract-amqp-test:<span class="hl-number">0.4</span>.<span class="hl-number">0</span>-SNAPSHOT:stubs
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> amqp</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">server</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> port</span>: <span class="hl-number">0</span></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_triggering_the_message" href="#_triggering_the_message"></a>Triggering the message</h4></div></div></div><p>So to trigger a message using the contract above we’ll use the <code class="literal">StubTrigger</code> interface as follows.</p><pre class="programlisting">stubTrigger.trigger(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"contract-test.person.created.event"</span>)</pre><p>The message has the destination <code class="literal">contract-test.exchange</code> so the Spring AMQP stub runner integration looks for bindings related to this exchange.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Binding binding() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> BindingBuilder.bind(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Queue(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"test.queue"</span>)).to(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> DirectExchange(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"contract-test.exchange"</span>)).with(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"#"</span>);
|
|
}</pre><p>The binding definition binds the queue <code class="literal">test.queue</code>.
|
|
So the following listener definition is a match and is invoked with the contract message.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> SimpleMessageListenerContainer simpleMessageListenerContainer(ConnectionFactory connectionFactory,
|
|
MessageListenerAdapter listenerAdapter) {
|
|
SimpleMessageListenerContainer container = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> SimpleMessageListenerContainer();
|
|
container.setConnectionFactory(connectionFactory);
|
|
container.setQueueNames(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"test.queue"</span>);
|
|
container.setMessageListener(listenerAdapter);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> container;
|
|
}</pre><p>Also, the following annotated listener represents a match and would be invoked.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RabbitListener(bindings = @QueueBinding(
|
|
value = @Queue(value = "test.queue"),
|
|
exchange = @Exchange(value = "contract-test.exchange", ignoreDeclarationExceptions = "true")))</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> handlePerson(Person person) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.person = person;
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The message is directly handed over to the <code class="literal">onMessage</code> method of the <code class="literal">MessageListener</code> associated with the matching <code class="literal">SimpleMessageListenerContainer</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_spring_amqp_test_configuration" href="#_spring_amqp_test_configuration"></a>Spring AMQP Test Configuration</h4></div></div></div><p>In order to avoid that Spring AMQP is trying to connect to a running broker during our tests we configure a mock <code class="literal">ConnectionFactory</code>.</p><p>To disable the mocked ConnectionFactory set the property <code class="literal">stubrunner.amqp.mockConnection=false</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">stubrunner</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> amqp</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> mockConnection</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">false</span></pre></div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_contract_dsl" href="#_contract_dsl"></a>84. Contract DSL</h2></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Remember that inside the contract file you have to provide the fully qualified name to
|
|
the <code class="literal">Contract</code> class and the <code class="literal">make</code> static import i.e. <code class="literal">org.springframework.cloud.spec.Contract.make { …​ }</code>.
|
|
You can also provide an import to the <code class="literal">Contract</code> class <code class="literal">import org.springframework.cloud.spec.Contract</code> and then call
|
|
<code class="literal">Contract.make { …​ }</code></p></td></tr></table></div><p>Contract DSL is written in Groovy, but don’t be alarmed if you didn’t use Groovy before. Knowledge of the language is not really needed as our DSL uses only
|
|
a tiny subset of it (namely literals, method calls and closures). What’s more the DSL is designed to be programmer-readable without any knowledge of the DSL itself -
|
|
it’s statically typed.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Spring Cloud Contract supports defining multiple contracts in a single file!</p></td></tr></table></div><p>The Contract is present in the <code class="literal">spring-cloud-contract-spec</code> module of the Spring Cloud Contract Verifier repository.</p><p>Let’s look at full example of a contract definition.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'PUT'</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/api/12'</span>
|
|
headers {
|
|
header <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Type'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/vnd.org.springframework.cloud.contract.verifier.twitter-places-analyzer.v1+json'</span>
|
|
}
|
|
body <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'\
|
|
</span> [{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"created_at"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Sat Jul 26 09:38:57 +0000 2014"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"id"</span>: <span class="hl-number">492967299297845248</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"id_str"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"492967299297845248"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"text"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Gonna see you at Warsaw"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"place"</span>:
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"attributes"</span>:{},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bounding_box"</span>:
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"coordinates"</span>:
|
|
[[
|
|
[-<span class="hl-number">77.119759</span>,<span class="hl-number">38.791645</span>],
|
|
[-<span class="hl-number">76.909393</span>,<span class="hl-number">38.791645</span>],
|
|
[-<span class="hl-number">76.909393</span>,<span class="hl-number">38.995548</span>],
|
|
[-<span class="hl-number">77.119759</span>,<span class="hl-number">38.995548</span>]
|
|
]],
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"type"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Polygon"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"country"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"United States"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"country_code"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"US"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"full_name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Washington, DC"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"id"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"01fbe706f872cb32"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Washington"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"place_type"</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"city"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://api.twitter.com/1/geo/id/01fbe706f872cb32.json"</span>
|
|
}
|
|
}]
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span> }
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
}</pre><p>Not all features of the DSL are used in example above. If you didn’t find what you are looking for, please check next paragraphs on this page.</p><div class="blockquote"><blockquote class="blockquote"><p>You can easily compile Contracts to WireMock stubs mapping using standalone maven command: <code class="literal">mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert</code>.</p></blockquote></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_limitations_2" href="#_limitations_2"></a>84.1 Limitations</h2></div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Spring Cloud Contract Verifier doesn’t support XML properly. Please use JSON or help us implement this feature.</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>The support for the verification of size of JSON arrays is experimental. If you want to turn it on please provide
|
|
the value of a system property <code class="literal">spring.cloud.contract.verifier.assert.size</code> equal to <code class="literal">true</code>. By default this feature is set to
|
|
<code class="literal">false</code>. You can also provide the <code class="literal">assertJsonSize</code> property in the plugin configuration.</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Due to the fact that JSON structure can have any form it’s sometimes impossible to parse it properly when using
|
|
the <code class="literal">value(consumer(…​), producer(…​))</code> notation when using that in GString. That’s why we highly recommend using the
|
|
Groovy Map notation.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_common_top_level_elements" href="#_common_top_level_elements"></a>84.2 Common Top-Level elements</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_description" href="#_description"></a>84.2.1 Description</h3></div></div></div><p>You can add a <code class="literal">description</code> to your contract that is nothing else but an arbitrary text. Example:</p><pre class="programlisting"> org.springframework.cloud.contract.spec.Contract.make {
|
|
description(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span>given:
|
|
An input
|
|
when:
|
|
Sth happens
|
|
then:
|
|
Output
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">')
|
|
</span> }</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_name" href="#_name"></a>84.2.2 Name</h3></div></div></div><p>You can provide a name of your contract. Let’s assume that you’ve provided a name <code class="literal">should register a user</code>.
|
|
If you do this then the name of the autogenerated test will be equal to <code class="literal">validate_should_register_a_user</code>.
|
|
Also the name of the stub will be <code class="literal">should_register_a_user.json</code> in case of a WireMock stub.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Please ensure that the name doesn’t contain any characters that will make the generated test
|
|
not possible to compile. Also remember that if you provide the same name for multiple contracts then your
|
|
autogenerated tests will fail to compile and your generated stubs will override each other.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_ignoring_contracts" href="#_ignoring_contracts"></a>84.2.3 Ignoring contracts</h3></div></div></div><p>If you want to ignore a contract you can either set a value of ignored contracts in the plugin configuration
|
|
or just set the <code class="literal">ignored</code> property on the contract itself:</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
ignored()
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_http_top_level_elements" href="#_http_top_level_elements"></a>84.3 HTTP Top-Level Elements</h2></div></div></div><p>Following methods can be called in the top-level closure of a contract definition. Request and response are mandatory, priority is optional.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Definition of HTTP request part of the contract</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (this can be a valid request or invalid depending</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// on type of contract being specified).</span>
|
|
request {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Definition of HTTP response part of the contract</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// (a service implementing this contract should respond</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// with following response after receiving request</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// specified in "request" part above).</span>
|
|
response {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Contract priority, which can be used for overriding</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// contracts (1 is highest). Priority is optional.</span>
|
|
priority <span class="hl-number">1</span>
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_request" href="#_request"></a>84.4 Request</h2></div></div></div><p>HTTP protocol requires only <span class="strong"><strong>method and address</strong></span> to be specified in a request. The same information is mandatory in request definition of the Contract.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// HTTP request method (GET/POST/PUT/DELETE).</span>
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Path component of request URL is specified as follows.</span>
|
|
urlPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/users'</span>)
|
|
}
|
|
|
|
response {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
}</pre><p>It is possible to specify whole <code class="literal">url</code> instead of just path, but <code class="literal">urlPath</code> is the recommended way as it makes the tests <span class="strong"><strong>host-independent</strong></span>.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Specifying `url` and `urlPath` in one contract is illegal.</span>
|
|
url(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'http://localhost:8888/users'</span>)
|
|
}
|
|
|
|
response {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
}</pre><p>Request may contain <span class="strong"><strong>query parameters</strong></span>, which are specified in a closure nested in a call to <code class="literal">urlPath</code> or <code class="literal">url</code>.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
|
|
urlPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/users'</span>) {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Each parameter is specified in form</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `'paramName' : paramValue` where parameter value</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// may be a simple literal or one of matcher functions,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// all of which are used in this example.</span>
|
|
queryParameters {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// If a simple literal is used as value</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// default matcher function is used (equalTo)</span>
|
|
parameter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'limit'</span>: <span class="hl-number">100</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `equalTo` function simply compares passed value</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// using identity operator (==).</span>
|
|
parameter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'filter'</span>: equalTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"email"</span>)
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `containing` function matches strings</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// that contains passed substring.</span>
|
|
parameter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'gender'</span>: value(consumer(containing(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[mf]"</span>)), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'mf'</span>))
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `matching` function tests parameter</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// against passed regular expression.</span>
|
|
parameter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'offset'</span>: value(consumer(matching(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[0-9]+"</span>)), producer(<span class="hl-number">123</span>))
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `notMatching` functions tests if parameter</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// does not match passed regular expression.</span>
|
|
parameter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'loginStartsWith'</span>: value(consumer(notMatching(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".{0,2}"</span>)), producer(<span class="hl-number">3</span>))
|
|
}
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
|
|
response {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
}</pre><p>It may contain additional <span class="strong"><strong>request headers</strong></span>…​</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Each header is added in form `'Header-Name' : 'Header-Value'`.</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// there are also some helper methods</span>
|
|
headers {
|
|
header <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'key'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'value'</span>
|
|
contentType(applicationJson())
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
|
|
response {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
}</pre><p>…​and a <span class="strong"><strong>request body</strong></span>.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Currently only JSON format of request body is supported.</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Format will be determined from a header or body's content.</span>
|
|
body <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{ "login" : "john", "name": "John The Contract" }'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>
|
|
}
|
|
|
|
response {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
}</pre><p>Request may contain <span class="strong"><strong>multipart</strong></span> elements. Just call the <code class="literal">multipart()</code> method.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract contractDsl = org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"PUT"</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/multipart"</span>
|
|
headers {
|
|
contentType(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'multipart/form-data;boundary=AaB03x'</span>)
|
|
}
|
|
multipart(
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// key (parameter name), value (parameter value) pair</span>
|
|
formParameter: $(c(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'".+"'</span>)), p(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'"formParameterValue"'</span>)),
|
|
someBooleanParameter: $(c(regex(anyBoolean())), p(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'true'</span>)),
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// a named parameter (e.g. with `file` name) that represents file with</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// `name` and `content`. You can also call `named("fileName", "fileContent")`</span>
|
|
file: named(
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// name of the file</span>
|
|
name: $(c(regex(nonEmpty())), p(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'filename.csv'</span>)),
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// content of the file</span>
|
|
content: $(c(regex(nonEmpty())), p(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'file content'</span>)))
|
|
)
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
}</pre><p>In this example we defined parameters either directly by using the map notation,
|
|
where the value can be a dynamic property (e.g. <code class="literal">formParameter: $(consumer(…​), producer(…​))</code>)
|
|
or by using the <code class="literal">named(…​)</code> method that allows you to set a named parameter.
|
|
A named parameter can set a <code class="literal">name</code> and <code class="literal">content</code>. You can call it either via
|
|
a method with 2 arguments: e.g. <code class="literal">named("fileName", "fileContent")</code> or
|
|
via a map notation <code class="literal">named(name: "fileName", content: "fileContent")</code>.</p><p>From this contract the generated test will look more or less like this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"multipart/form-data;boundary=AaB03x"</span>)
|
|
.param(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"formParameter"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\"formParameterValue\""</span>)
|
|
.param(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"someBooleanParameter"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"true"</span>)
|
|
.multiPart(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"file"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"filename.csv"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"file content"</span>.getBytes());
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.put(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/multipart"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);</pre><p>The WireMock stub will look more or less like this:</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/multipart"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"PUT"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matches"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"multipart/form-data;boundary=AaB03x.*"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bodyPatterns"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matches"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".*--(.*)\\r\\nContent-Disposition: form-data; name=\\"</span>formParameter\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\\r\\n(Content-Type: .*\\r\\n)?(Content-Length: \\\\d+\\r\\n)?\\r\\n\\"</span>.+\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\\r\\n--\\\\1.*"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matches"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".*--(.*)\\r\\nContent-Disposition: form-data; name=\\"</span>someBooleanParameter\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\\r\\n(Content-Type: .*\\r\\n)?(Content-Length: \\\\d+\\r\\n)?\\r\\n(true|false)\\r\\n--\\\\1.*"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matches"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".*--(.*)\\r\\nContent-Disposition: form-data; name=\\"</span>file\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"; filename=\\"</span>[\\\\S\\\\s]+\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\\r\\n(Content-Type: .*\\r\\n)?(Content-Length: \\\\d+\\r\\n)?\\r\\n[\\\\S\\\\s]+\\r\\n--\\\\1.*"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span> : <span class="hl-number">200</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"transformers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response-template"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_response" href="#_response"></a>84.5 Response</h2></div></div></div><p>Minimal response must contain <span class="strong"><strong>HTTP status code</strong></span>.</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//...</span>
|
|
}
|
|
response {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Status code sent by the server</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// in response to request specified above.</span>
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
}</pre><p>Besides status response may contain <span class="strong"><strong>headers</strong></span> and <span class="strong"><strong>body</strong></span>, which are specified the same way as in the request (see previous paragraph).</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_dynamic_properties" href="#_dynamic_properties"></a>84.6 Dynamic properties</h2></div></div></div><p>The contract can contain some dynamic properties - timestamps / ids etc. You don’t want to enforce the consumers to stub their
|
|
clocks to always return the same value of time so that it gets matched by the stub. That’s why we allow you to provide the dynamic
|
|
parts in your contracts in two ways. One is to pass them directly in the
|
|
body and one to set them in a separate section called <code class="literal">testMatchers</code> and <code class="literal">stubMatchers</code>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_dynamic_properties_inside_the_body" href="#_dynamic_properties_inside_the_body"></a>84.6.1 Dynamic properties inside the body</h3></div></div></div><p>You can set the properties inside the body either via the <code class="literal">value</code> method</p><pre class="programlisting">value(consumer(...), producer(...))
|
|
value(c(...), p(...))
|
|
value(stub(...), test(...))
|
|
value(client(...), server(...))</pre><p>or if you’re using the Groovy map notation for body you can use the <code class="literal">$()</code> method</p><pre class="programlisting">$(consumer(...), producer(...))
|
|
$(c(...), p(...))
|
|
$(stub(...), test(...))
|
|
$(client(...), server(...))</pre><p>All of the aforementioned approaches are equal. That means that <code class="literal">stub</code> and <code class="literal">client</code> methods are aliases over the <code class="literal">consumer</code>
|
|
method. Let’s take a closer look at what we can do with those values in the subsequent sections.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_regular_expressions" href="#_regular_expressions"></a>84.6.2 Regular expressions</h3></div></div></div><p>You can use regular expressions to write your requests in Contract DSL. It is particularly useful when you want to indicate that a given response
|
|
should be provided for requests that follow a given pattern. Also, you can use it when you need to use patterns and not exact values both
|
|
for your test and your server side tests.</p><p>Please see the example below:</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>)
|
|
url $(consumer(~/\/[<span class="hl-number">0</span>-<span class="hl-number">9</span>]{<span class="hl-number">2</span>}/), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/12'</span>))
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body(
|
|
id: $(anyNumber()),
|
|
surname: $(
|
|
consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Kowalsky'</span>),
|
|
producer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[a-zA-Z]+'</span>))
|
|
),
|
|
name: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Jan'</span>,
|
|
created: $(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'2014-02-02 12:23:43'</span>), producer(execute(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'currentDate(it)'</span>))),
|
|
correlationId: value(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'5d1f9fef-e0dc-4f3d-a7e4-72d2220dd827'</span>),
|
|
producer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'</span>))
|
|
)
|
|
)
|
|
headers {
|
|
header <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Type'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'text/plain'</span>
|
|
}
|
|
}
|
|
}</pre><p>You can also provide only one side of the communication using a regular expression. If you do that then automatically we’ll
|
|
provide the generated string that matches the provided regular expression. For example:</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'PUT'</span>
|
|
url value(consumer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/foo/[0-9]{5}'</span>)))
|
|
body([
|
|
requestElement: $(consumer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[0-9]{5}'</span>)))
|
|
])
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>, $(consumer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application\\/vnd\\.fraud\\.v1\\+json;.*'</span>))))
|
|
}
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body([
|
|
responseElement: $(producer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[0-9]{7}'</span>)))
|
|
])
|
|
headers {
|
|
contentType(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json"</span>)
|
|
}
|
|
}
|
|
}</pre><p>In this example for request and response the opposite side of the communication will have the respective data generated.</p><p>Spring Cloud Contract comes with a series of predefined regular expressions that you can use in your contracts.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern TRUE_OR_FALSE = Pattern.compile(/(true|false)/)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern ONLY_ALPHA_UNICODE = Pattern.compile(/[\p{L}]*/)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern NUMBER = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'-?\\d*(\\.\\d+)?'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern IP_ADDRESS = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern HOSTNAME_PATTERN = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'((http[s]?|ftp):/)/?([^:/\\s]+)(:[0-9]{1,5})?'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern EMAIL = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,6}'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern URL = UrlHelper.URL
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern UUID = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern ANY_DATE = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'(\\d\\d\\d\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern ANY_DATE_TIME = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern ANY_TIME = Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern NON_EMPTY = Pattern.compile(/[\S\s]+/)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern NON_BLANK = Pattern.compile(/^\s*\S[\S\s]*/)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> Pattern ISO8601_WITH_OFFSET = Pattern.compile(/([<span class="hl-number">0</span>-<span class="hl-number">9</span>]{<span class="hl-number">4</span>})-(<span class="hl-number">1</span>[<span class="hl-number">0</span>-<span class="hl-number">2</span>]|<span class="hl-number">0</span>[<span class="hl-number">1</span>-<span class="hl-number">9</span>])-(<span class="hl-number">3</span>[<span class="hl-number">01</span>]|<span class="hl-number">0</span>[<span class="hl-number">1</span>-<span class="hl-number">9</span>]|[<span class="hl-number">12</span>][<span class="hl-number">0</span>-<span class="hl-number">9</span>])T(<span class="hl-number">2</span>[<span class="hl-number">0</span>-<span class="hl-number">3</span>]|[<span class="hl-number">01</span>][<span class="hl-number">0</span>-<span class="hl-number">9</span>]):([<span class="hl-number">0</span>-<span class="hl-number">5</span>][<span class="hl-number">0</span>-<span class="hl-number">9</span>]):([<span class="hl-number">0</span>-<span class="hl-number">5</span>][<span class="hl-number">0</span>-<span class="hl-number">9</span>])(\.\d{<span class="hl-number">3</span>})?(Z|[+-][<span class="hl-number">01</span>]\d:[<span class="hl-number">0</span>-<span class="hl-number">5</span>]\d)/)
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">protected</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> Pattern anyOf(String... values){
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Pattern.compile(values.collect({<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"^$it\$"</span>}).join(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"|"</span>))
|
|
}
|
|
|
|
String onlyAlphaUnicode() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> ONLY_ALPHA_UNICODE.pattern()
|
|
}
|
|
|
|
String number() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> NUMBER.pattern()
|
|
}
|
|
|
|
String anyBoolean() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> TRUE_OR_FALSE.pattern()
|
|
}
|
|
|
|
String ipAddress() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> IP_ADDRESS.pattern()
|
|
}
|
|
|
|
String hostname() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> HOSTNAME_PATTERN.pattern()
|
|
}
|
|
|
|
String email() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> EMAIL.pattern()
|
|
}
|
|
|
|
String url() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> URL.pattern()
|
|
}
|
|
|
|
String uuid(){
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> UUID.pattern()
|
|
}
|
|
|
|
String isoDate() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> ANY_DATE.pattern()
|
|
}
|
|
|
|
String isoDateTime() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> ANY_DATE_TIME.pattern()
|
|
}
|
|
|
|
String isoTime() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> ANY_TIME.pattern()
|
|
}
|
|
|
|
String iso8601WithOffset() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> ISO8601_WITH_OFFSET.pattern()
|
|
}
|
|
|
|
String nonEmpty() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> NON_EMPTY.pattern()
|
|
}
|
|
|
|
String nonBlank() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> NON_BLANK.pattern()
|
|
}</pre><p>so in your contract you can use it like this</p><pre class="programlisting">Contract dslWithOptionalsInString = Contract.make {
|
|
priority <span class="hl-number">1</span>
|
|
request {
|
|
method POST()
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/users/password'</span>
|
|
headers {
|
|
contentType(applicationJson())
|
|
}
|
|
body(
|
|
email: $(consumer(optional(regex(email()))), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'abc@abc.com'</span>)),
|
|
callback_url: $(consumer(regex(hostname())), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'http://partners.com'</span>))
|
|
)
|
|
}
|
|
response {
|
|
status <span class="hl-number">404</span>
|
|
headers {
|
|
contentType(applicationJson())
|
|
}
|
|
body(
|
|
code: value(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"123123"</span>), producer(optional(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"123123"</span>))),
|
|
message: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"User not found by email = [${value(producer(regex(email())), consumer('not.existing@user.com'))}]"</span>
|
|
)
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_passing_optional_parameters" href="#_passing_optional_parameters"></a>84.6.3 Passing optional parameters</h3></div></div></div><p>It is possible to provide optional parameters in your contract. It’s only possible to have optional parameter for the:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="emphasis"><em>STUB</em></span> side of the Request</li><li class="listitem"><span class="emphasis"><em>TEST</em></span> side of the Response</li></ul></div><p>Example:</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
priority <span class="hl-number">1</span>
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'POST'</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/users/password'</span>
|
|
headers {
|
|
contentType(applicationJson())
|
|
}
|
|
body(
|
|
email: $(consumer(optional(regex(email()))), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'abc@abc.com'</span>)),
|
|
callback_url: $(consumer(regex(hostname())), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'http://partners.com'</span>))
|
|
)
|
|
}
|
|
response {
|
|
status <span class="hl-number">404</span>
|
|
headers {
|
|
header <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Type'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>
|
|
}
|
|
body(
|
|
code: value(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"123123"</span>), producer(optional(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"123123"</span>)))
|
|
)
|
|
}
|
|
}</pre><p>By wrapping a part of the body with the <code class="literal">optional()</code> method you are in fact creating a regular expression that should be present 0 or more times.</p><p>That way for the example above the following test would be generated if you pick Spock:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"
|
|
</span> given:
|
|
def request = given()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json"</span>)
|
|
.body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{"email":"abc@abc.com","callback_url":"http://partners.com"}'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
|
|
when:
|
|
def response = given().spec(request)
|
|
.post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/users/password"</span>)
|
|
|
|
then:
|
|
response.statusCode == <span class="hl-number">404</span>
|
|
response.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Type'</span>) == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>
|
|
and:
|
|
DocumentContext parsedJson = JsonPath.parse(response.body.asString())
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['code']"</span>).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"(123123)?"</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"</span></pre><p>and the following stub:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span>{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/users/password"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"POST"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bodyPatterns"</span> : [ {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.['email'] =~ /([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,6})?/)]"</span>
|
|
}, {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.['callback_url'] =~ /((http[s]?|ftp):\\\\/)\\\\/?([^:\\\\/\\\\s]+)(:[0-9]{1,5})?/)]"</span>
|
|
} ],
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"equalTo"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json"</span>
|
|
}
|
|
}
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span> : <span class="hl-number">404</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\\"</span>code\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span><span class="hl-number">123123</span>\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">",\\"</span>message\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span>User not found by email == [not.existing<em><span class="hl-annotation" style="color: gray">@user.com]\\"}",</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json"</span>
|
|
}
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"priority"</span> : <span class="hl-number">1</span>
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_executing_custom_methods_on_server_side" href="#_executing_custom_methods_on_server_side"></a>84.6.4 Executing custom methods on server side</h3></div></div></div><p>It is also possible to define a method call to be executed on the server side during the test. Such a method can be added to the class defined as "baseClassForTests"
|
|
in the configuration. Example:</p><p><span class="strong"><strong>Contract</strong></span></p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'PUT'</span>
|
|
url $(consumer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'^/api/[0-9]{2}$'</span>)), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/api/12'</span>))
|
|
headers {
|
|
header <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Type'</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span>
|
|
}
|
|
body <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'\
|
|
</span> [{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"text"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Gonna see you at Warsaw"</span>
|
|
}]
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span> }
|
|
response {
|
|
body (
|
|
path: $(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/api/12'</span>), producer(regex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'^/api/[0-9]{2}$'</span>))),
|
|
correlationId: $(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'1223456'</span>), producer(execute(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'isProperCorrelationId($it)'</span>)))
|
|
)
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
}</pre><p><span class="strong"><strong>Base class</strong></span></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">abstract</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> BaseMockMvcSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
|
|
|
def setup() {
|
|
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> PairIdController())
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> isProperCorrelationId(Integer correlationId) {
|
|
assert correlationId == <span class="hl-number">123456</span>
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> isEmpty(String value) {
|
|
assert value == null
|
|
}
|
|
|
|
}</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>You can’t use both a String and <code class="literal">execute</code> to perform concatenation. E.g. calling
|
|
<code class="literal">header('Authorization', 'Bearer ' + execute('authToken()'))</code> will lead to improper results.
|
|
To make this work just call <code class="literal">header('Authorization', execute('authToken()'))</code> and ensure that
|
|
the <code class="literal">authToken()</code> method returns everything that you need.</p></td></tr></table></div><p>The type of the object read from the JSON can be one of the followings depending on the
|
|
JSON path:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">String</code> if you point to a <code class="literal">String</code> value in a JSON</li><li class="listitem"><code class="literal">JSONArray</code> if you point to a <code class="literal">List</code> in a JSON</li><li class="listitem"><code class="literal">Map</code> if you point to a <code class="literal">Map</code> in a JSON</li><li class="listitem">proper <code class="literal">Number</code> if you point to <code class="literal">Integer</code>, <code class="literal">Double</code> etc. in a JSON</li><li class="listitem"><code class="literal">Boolean</code> if you point to a <code class="literal">Boolean</code> in a JSON</li></ul></div><p>In the request part of the contract you can specify that the <code class="literal">body</code> should be
|
|
taken from a method.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>You have to provide both the consumer and the producer side
|
|
and the <code class="literal">execute</code> part can be applied for the whole body. Not for parts of it!</p></td></tr></table></div><p>Example:</p><pre class="programlisting">Contract contractDsl = Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/something'</span>
|
|
body(
|
|
$(c(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>), p(execute(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"hashCode()"</span>)))
|
|
)
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
}</pre><p>This will result in calling the <code class="literal">hashCode()</code> method in the request body.
|
|
It would more or less like this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given()
|
|
.body(hashCode());
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/something"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_referencing_request_from_response" href="#_referencing_request_from_response"></a>84.6.5 Referencing request from response</h3></div></div></div><p>The best situation is to provide fixed values but sometimes you need to reference a request in your response.
|
|
In order to do this you can profit from the <code class="literal">fromRequest()</code> method that allows you to reference a bunch
|
|
of elements from the HTTP request. You can use the following options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">fromRequest().url()</code> - return the request URL</li><li class="listitem"><code class="literal">fromRequest().query(String key)</code> - return the first query parameter with a given name</li><li class="listitem"><code class="literal">fromRequest().query(String key, int index)</code> - return the nth query parameter with a given name</li><li class="listitem"><code class="literal">fromRequest().header(String key)</code> - return the first header with a given name</li><li class="listitem"><code class="literal">fromRequest().header(String key, int index)</code> - return the nth header with a given name</li><li class="listitem"><code class="literal">fromRequest().body()</code> - return the full request body</li><li class="listitem"><code class="literal">fromRequest().body(String jsonPath)</code> - return the element from the request that matches the JSON Path</li></ul></div><p>Let’s take a look at the following contract</p><pre class="programlisting">Contract contractDsl = Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>
|
|
url(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/api/v1/xxxx'</span>) {
|
|
queryParameters {
|
|
parameter(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>)
|
|
parameter(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar2"</span>)
|
|
}
|
|
}
|
|
headers {
|
|
header(authorization(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret"</span>)
|
|
header(authorization(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret2"</span>)
|
|
}
|
|
body(foo: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>, baz: <span class="hl-number">5</span>)
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
headers {
|
|
header(authorization(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo ${fromRequest().header(authorization())} bar"</span>)
|
|
}
|
|
body(
|
|
url: fromRequest().url(),
|
|
param: fromRequest().query(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>),
|
|
paramIndex: fromRequest().query(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>, <span class="hl-number">1</span>),
|
|
authorization: fromRequest().header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Authorization"</span>),
|
|
authorization2: fromRequest().header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Authorization"</span>, <span class="hl-number">1</span>),
|
|
fullBody: fromRequest().body(),
|
|
responseFoo: fromRequest().body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.foo'</span>),
|
|
responseBaz: fromRequest().body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.baz'</span>),
|
|
responseBaz2: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Bla bla ${fromRequest().body('$.foo')} bla bla"</span>
|
|
)
|
|
}
|
|
}</pre><p>Running a JUnit test generation will lead in creation of a test looking more or less like this</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Authorization"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret"</span>)
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Authorization"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret2"</span>)
|
|
.body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"foo\":\"bar\",\"baz\":5}"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>,<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>,<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar2"</span>)
|
|
.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/api/v1/xxxx"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);
|
|
assertThat(response.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Authorization"</span>)).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo secret bar"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/api/v1/xxxx"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fullBody"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"foo\":\"bar\",\"baz\":5}"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"paramIndex"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar2"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"responseFoo"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"authorization2"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret2"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"responseBaz"</span>).isEqualTo(<span class="hl-number">5</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"responseBaz2"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Bla bla bar bla bla"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"param"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"authorization"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret"</span>);</pre><p>As you can see elements from the request have been properly referenced in the response.</p><p>The generated WireMock stub will look more or less like this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"urlPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/api/v1/xxxx"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"POST"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Authorization"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"equalTo"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret2"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"queryParameters"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"equalTo"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar2"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bodyPatterns"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.baz == 5)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.foo == 'bar')]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span> : <span class="hl-number">200</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"url\":\"{{{request.url}}}\",\"param\":\"{{{request.query.foo.[0]}}}\",\"paramIndex\":\"{{{request.query.foo.[1]}}}\",\"authorization\":\"{{{request.headers.Authorization.[0]}}}\",\"authorization2\":\"{{{request.headers.Authorization.[1]}}}\",\"fullBody\":\"{{{escapejsonbody}}}\",\"responseFoo\":\"{{{jsonpath this '$.foo'}}}\",\"responseBaz\":{{{jsonpath this '$.baz'}}} ,\"responseBaz2\":\"Bla bla {{{jsonpath this '$.foo'}}} bla bla\"}"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Authorization"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{{{request.headers.Authorization.[0]}}}"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"transformers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response-template"</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>So sending a request as the one presented in the <code class="literal">request</code> part of the contract will lead in sending the following
|
|
response body</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/api/v1/xxxx?foo=bar&foo=bar2"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"param"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"paramIndex"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar2"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"authorization"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"authorization2"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"secret2"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fullBody"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"foo\":\"bar\",\"baz\":5}"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"responseFoo"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"responseBaz"</span> : <span class="hl-number">5</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"responseBaz2"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Bla bla bar bla bla"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>This feature will work only with WireMock having version greater or equal to 2.5.1. We’re using WireMock’s
|
|
<code class="literal">response-template</code> response transformer. It’s using Handlebars to convert the Mustache <code class="literal">{{{ }}}</code> templates into
|
|
proper values. Additionally we’re registering 2 helper functions. <code class="literal">escapejsonbody</code> - that escapes the request
|
|
body in a format that can be embedded in a JSON. Another is <code class="literal">jsonpath</code> that for a given parameter knows how to
|
|
find an object in the request body.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_dynamic_properties_in_matchers_sections" href="#_dynamic_properties_in_matchers_sections"></a>84.6.6 Dynamic properties in matchers sections</h3></div></div></div><p>If you’ve been working with <a class="link" href="https://docs.pact.io/" target="_top">Pact</a> this might seem familiar. Quite a few users
|
|
are used to having a separation between the body and setting dynamic parts of your contract.</p><p>That’s why you can profit from two separate sections. One is called <code class="literal">stubMatchers</code> where you can
|
|
define the dynamic values that should end up in a stub. You can set it in the <code class="literal">request</code> or <code class="literal">inputMessage</code>
|
|
part of your contract. The other is called <code class="literal">testMatchers</code> which is present in the <code class="literal">response</code> or
|
|
<code class="literal">outputMessage</code> side of the contract.</p><p>Currently we support only JSON Path based matchers with the following matching possibilities.
|
|
For <code class="literal">stubMatchers</code>:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">byEquality()</code> - the value taken from the response via the provided JSON Path needs
|
|
to be equal to the provided value in the contract</li><li class="listitem"><code class="literal">byRegex(…​)</code> - the value taken from the response via the provided JSON Path needs
|
|
to match the regex</li><li class="listitem"><code class="literal">byDate()</code> - the value taken from the response via the provided JSON Path needs to
|
|
match the regex for ISO Date</li><li class="listitem"><code class="literal">byTimestamp()</code> - the value taken from the response via the provided JSON Path needs
|
|
to match the regex for ISO DateTime</li><li class="listitem"><code class="literal">byTime()</code> - the value taken from the response via the provided JSON Path needs to
|
|
match the regex for ISO Time</li></ul></div><p>For <code class="literal">testMatchers</code>:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">byEquality()</code> - the value taken from the response via the provided JSON Path needs
|
|
to be equal to the provided value in the contract</li><li class="listitem"><code class="literal">byRegex(…​)</code> - the value taken from the response via the provided JSON Path needs
|
|
to match the regex</li><li class="listitem"><code class="literal">byDate()</code> - the value taken from the response via the provided JSON Path needs to
|
|
match the regex for ISO Date</li><li class="listitem"><code class="literal">byTimestamp()</code> - the value taken from the response via the provided JSON Path needs
|
|
to match the regex for ISO DateTime</li><li class="listitem"><code class="literal">byTime()</code> - the value taken from the response via the provided JSON Path needs to
|
|
match the regex for ISO Time</li><li class="listitem"><code class="literal">byType()</code> - the value taken from the response via the provided JSON Path needs to
|
|
be of the same type as the type defined in the body of the response in the contract.
|
|
<code class="literal">byType</code> can take a closure where you can set <code class="literal">minOccurrence</code> and <code class="literal">maxOccurrence</code>.
|
|
That way you can assert on the size of the flattened collection. To check the size
|
|
of an unflattened collection, use a custom method via <code class="literal">byCommand(…​)</code> testMatcher.</li><li class="listitem"><p class="simpara"><code class="literal">byCommand(…​)</code> - the value taken from the response via the provided JSON Path will be
|
|
passed as an input to the custom method that you’re providing. E.g. <code class="literal">byCommand('foo($it)')</code>
|
|
will result in calling a <code class="literal">foo</code> method to which the value matching the JSON Path will get
|
|
passed.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p class="simpara">The type of the object read from the JSON can be one of the followings depending on the
|
|
JSON path:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><code class="literal">String</code> if you point to a <code class="literal">String</code> value in a JSON</li><li class="listitem"><code class="literal">JSONArray</code> if you point to a <code class="literal">List</code> in a JSON</li><li class="listitem"><code class="literal">Map</code> if you point to a <code class="literal">Map</code> in a JSON</li><li class="listitem">proper <code class="literal">Number</code> if you point to <code class="literal">Integer</code>, <code class="literal">Double</code> etc. in a JSON</li><li class="listitem"><code class="literal">Boolean</code> if you point to a <code class="literal">Boolean</code> in a JSON</li></ul></div></li></ul></div></li></ul></div><p>Let’s take a look at the following example:</p><pre class="programlisting">Contract contractDsl = Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>
|
|
urlPath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/get'</span>
|
|
body([
|
|
duck: <span class="hl-number">123</span>,
|
|
alpha: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"abc"</span>,
|
|
number: <span class="hl-number">123</span>,
|
|
aBoolean: true,
|
|
date: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-01-01"</span>,
|
|
dateTime: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-01-01T01:23:45"</span>,
|
|
time: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"01:02:34"</span>,
|
|
valueWithoutAMatcher: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>,
|
|
valueWithTypeMatch: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"string"</span>,
|
|
key: [
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'complex.key'</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
]
|
|
])
|
|
stubMatchers {
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.duck'</span>, byRegex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[0-9]{3}"</span>))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.duck'</span>, byEquality())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.alpha'</span>, byRegex(onlyAlphaUnicode()))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.alpha'</span>, byEquality())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.number'</span>, byRegex(number()))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.aBoolean'</span>, byRegex(anyBoolean()))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.date'</span>, byDate())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.dateTime'</span>, byTimestamp())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.time'</span>, byTime())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\$.['key'].['complex.key']"</span>, byEquality())
|
|
}
|
|
headers {
|
|
contentType(applicationJson())
|
|
}
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body([
|
|
duck: <span class="hl-number">123</span>,
|
|
alpha: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"abc"</span>,
|
|
number: <span class="hl-number">123</span>,
|
|
aBoolean: true,
|
|
date: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-01-01"</span>,
|
|
dateTime: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2017-01-01T01:23:45"</span>,
|
|
time: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"01:02:34"</span>,
|
|
valueWithoutAMatcher: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>,
|
|
valueWithTypeMatch: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"string"</span>,
|
|
valueWithMin: [
|
|
<span class="hl-number">1</span>,<span class="hl-number">2</span>,<span class="hl-number">3</span>
|
|
],
|
|
valueWithMax: [
|
|
<span class="hl-number">1</span>,<span class="hl-number">2</span>,<span class="hl-number">3</span>
|
|
],
|
|
valueWithMinMax: [
|
|
<span class="hl-number">1</span>,<span class="hl-number">2</span>,<span class="hl-number">3</span>
|
|
],
|
|
valueWithMinEmpty: [],
|
|
valueWithMaxEmpty: [],
|
|
key: [
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'complex.key'</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
]
|
|
])
|
|
testMatchers {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// asserts the jsonpath value against manual regex</span>
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.duck'</span>, byRegex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[0-9]{3}"</span>))
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// asserts the jsonpath value against the provided value</span>
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.duck'</span>, byEquality())
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// asserts the jsonpath value against some default regex</span>
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.alpha'</span>, byRegex(onlyAlphaUnicode()))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.alpha'</span>, byEquality())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.number'</span>, byRegex(number()))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.aBoolean'</span>, byRegex(anyBoolean()))
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// asserts vs inbuilt time related regex</span>
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.date'</span>, byDate())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.dateTime'</span>, byTimestamp())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.time'</span>, byTime())
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// asserts that the resulting type is the same as in response body</span>
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.valueWithTypeMatch'</span>, byType())
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.valueWithMin'</span>, byType {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// results in verification of size of array (min 1)</span>
|
|
minOccurrence(<span class="hl-number">1</span>)
|
|
})
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.valueWithMax'</span>, byType {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// results in verification of size of array (max 3)</span>
|
|
maxOccurrence(<span class="hl-number">3</span>)
|
|
})
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.valueWithMinMax'</span>, byType {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// results in verification of size of array (min 1 & max 3)</span>
|
|
minOccurrence(<span class="hl-number">1</span>)
|
|
maxOccurrence(<span class="hl-number">3</span>)
|
|
})
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.valueWithMinEmpty'</span>, byType {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// results in verification of size of array (min 0)</span>
|
|
minOccurrence(<span class="hl-number">0</span>)
|
|
})
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.valueWithMaxEmpty'</span>, byType {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// results in verification of size of array (max 0)</span>
|
|
maxOccurrence(<span class="hl-number">0</span>)
|
|
})
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// will execute a method `assertThatValueIsANumber`</span>
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.duck'</span>, byCommand(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'assertThatValueIsANumber($it)'</span>))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\$.['key'].['complex.key']"</span>, byEquality())
|
|
}
|
|
headers {
|
|
contentType(applicationJson())
|
|
}
|
|
}
|
|
}</pre><p>In this example we’re providing the dynamic portions of the contract in the matchers sections.
|
|
For the request part you can see that for all fields but <code class="literal">valueWithoutAMatcher</code> we’re setting
|
|
explicitly the values of regular expressions we’d like the stub to contain. For the <code class="literal">valueWithoutAMatcher</code>
|
|
the verification will take place in the same way as without the usage of matchers - the test
|
|
will perform an equality check in this case.</p><p>For the response side in the <code class="literal">testMatchers</code> section we’re defining all the dynamic parts
|
|
in a similar manner. The only difference is that we have the <code class="literal">byType</code> matchers too. In that
|
|
case we’re checking 4 fields in the way that we’re verifying whether the response from the test
|
|
has a value whose JSON path matching the given field is of the same type as the one defined in the response body and:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">for <code class="literal">$.valueWithTypeMatch</code> - we’re just checking the whether the type is the same</li><li class="listitem">for <code class="literal">$.valueWithMin</code> - we’re checking the type and assert if the size is greater or equal to the min occurrence</li><li class="listitem">for <code class="literal">$.valueWithMax</code> - we’re checking the type and assert if the size is smaller or equal to the max occurrence</li><li class="listitem">for <code class="literal">$.valueWithMinMax</code> - we’re checking the type and assert if the size is between the min and max occurrence</li></ul></div><p>The resulting test would look more or less like this (note that we’re separating the autogenerated
|
|
assertions and the one from matchers with an <code class="literal">and</code> section):</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json"</span>)
|
|
.body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"duck\":123,\"alpha\":\"abc\",\"number\":123,\"aBoolean\":true,\"date\":\"2017-01-01\",\"dateTime\":\"2017-01-01T01:23:45\",\"time\":\"01:02:34\",\"valueWithoutAMatcher\":\"foo\",\"valueWithTypeMatch\":\"string\"}"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/get"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);
|
|
assertThat(response.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json.*"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"valueWithoutAMatcher"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.duck"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[0-9]{3}"</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.duck"</span>, Integer.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).isEqualTo(<span class="hl-number">123</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.alpha"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[\\p{L}]*"</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.alpha"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"abc"</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.number"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"-?\\d*(\\.\\d+)?"</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.aBoolean"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"(true|false)"</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.date"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"(\\d\\d\\d\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])"</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.dateTime"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])"</span>);
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.time"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])"</span>);
|
|
assertThat((Object) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithTypeMatch"</span>)).isInstanceOf(java.lang.String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
assertThat((Object) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMin"</span>)).isInstanceOf(java.util.List.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
assertThat((java.lang.Iterable) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMin"</span>, java.util.Collection.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).hasSizeGreaterThanOrEqualTo(<span class="hl-number">1</span>);
|
|
assertThat((Object) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMax"</span>)).isInstanceOf(java.util.List.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
assertThat((java.lang.Iterable) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMax"</span>, java.util.Collection.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).hasSizeLessThanOrEqualTo(<span class="hl-number">3</span>);
|
|
assertThat((Object) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMinMax"</span>)).isInstanceOf(java.util.List.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
assertThat((java.lang.Iterable) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMinMax"</span>, java.util.Collection.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).hasSizeBetween(<span class="hl-number">1</span>, <span class="hl-number">3</span>);
|
|
assertThat((Object) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMinEmpty"</span>)).isInstanceOf(java.util.List.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
assertThat((java.lang.Iterable) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMinEmpty"</span>, java.util.Collection.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).hasSizeGreaterThanOrEqualTo(<span class="hl-number">0</span>);
|
|
assertThat((Object) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMaxEmpty"</span>)).isInstanceOf(java.util.List.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
assertThat((java.lang.Iterable) parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.valueWithMaxEmpty"</span>, java.util.Collection.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).hasSizeLessThanOrEqualTo(<span class="hl-number">0</span>);
|
|
assertThatValueIsANumber(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.duck"</span>));</pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Notice that for the <code class="literal">byCommand</code> method we are calling the <code class="literal">assertThatValueIsANumber</code>. This method needs
|
|
to be defined in the test base class or should be statically imported to your tests.
|
|
Notice that the <code class="literal">byCommand</code> call was converted to <code class="literal">assertThatValueIsANumber(parsedJson.read("$.duck"));</code>. That means
|
|
that we took the method name and passed the proper JSON path as a parameter to it.</p></td></tr></table></div><p>and the WireMock stub like this:</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"urlPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/get"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"POST"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matches"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json.*"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bodyPatterns"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.['valueWithoutAMatcher'] == 'foo')]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.['valueWithTypeMatch'] == 'string')]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.['list'].['some'].['nested'][?(@.['anothervalue'] == 4)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.['list'].['someother'].['nested'][?(@.['anothervalue'] == 4)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.['list'].['someother'].['nested'][?(@.['json'] == 'with value')]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.duck =~ /([0-9]{3})/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.duck == 123)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.alpha =~ /([\\\\p{L}]*)/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.alpha == 'abc')]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.number =~ /(-?\\\\d*(\\\\.\\\\d+)?)/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.aBoolean =~ /((true|false))/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.date =~ /((\\\\d\\\\d\\\\d\\\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.dateTime =~ /(([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9]))/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.time =~ /((2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9]))/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.list.some.nested[?(@.json =~ /(.*)/)]"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span> : <span class="hl-number">200</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\\"</span>duck\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":123,\\"</span>alpha\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span>abc\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">",\\"</span>number\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":123,\\"</span>aBoolean\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":true,\\"</span>date\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span><span class="hl-number">2017</span>-<span class="hl-number">01</span>-<span class="hl-number">01</span>\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">",\\"</span>dateTime\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span><span class="hl-number">2017</span>-<span class="hl-number">01</span>-<span class="hl-number">01</span>T01:<span class="hl-number">23</span>:<span class="hl-number">45</span>\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">",\\"</span>time\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span><span class="hl-number">01</span>:<span class="hl-number">02</span>:<span class="hl-number">34</span>\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">",\\"</span>valueWithoutAMatcher\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span>foo\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">",\\"</span>valueWithTypeMatch\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":\\"</span>string\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">",\\"</span>valueWithMin\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":[1,2,3],\\"</span>valueWithMax\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":[1,2,3],\\"</span>valueWithMinMax\\<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">":[1,2,3]}"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you use a <code class="literal">matcher</code> then the part of the request / response that the <code class="literal">matcher</code> is addressing
|
|
via the JSON Path will get removed from assertion. In case of verifying a collection you have to create
|
|
matchers for <span class="strong"><strong>all</strong></span> elements of the collection.</p></td></tr></table></div><p>Let’s look at the following example:</p><pre class="programlisting">Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>
|
|
url(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/foo"</span>)
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body(events: [[
|
|
operation : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'EXPORT'</span>,
|
|
eventId : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'16f1ed75-0bcc-4f0d-a04d-3121798faf99'</span>,
|
|
status : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'OK'</span>
|
|
], [
|
|
operation : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'INPUT_PROCESSING'</span>,
|
|
eventId : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'3bb4ac82-6652-462f-b6d1-75e424a0024a'</span>,
|
|
status : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'OK'</span>
|
|
]
|
|
]
|
|
)
|
|
testMatchers {
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.events[0].operation'</span>, byRegex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'.+'</span>))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.events[0].eventId'</span>, byRegex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$'</span>))
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$.events[0].status'</span>, byRegex(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'.+'</span>))
|
|
}
|
|
}
|
|
}</pre><p>This will lead in creating the following test (showing just the assertion section)</p><pre class="programlisting">and:
|
|
DocumentContext parsedJson = JsonPath.parse(response.body.asString())
|
|
assertThatJson(parsedJson).array(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['events']"</span>).contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['eventId']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"16f1ed75-0bcc-4f0d-a04d-3121798faf99"</span>)
|
|
assertThatJson(parsedJson).array(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['events']"</span>).contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['operation']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"EXPORT"</span>)
|
|
assertThatJson(parsedJson).array(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['events']"</span>).contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['operation']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"INPUT_PROCESSING"</span>)
|
|
assertThatJson(parsedJson).array(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['events']"</span>).contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['eventId']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"3bb4ac82-6652-462f-b6d1-75e424a0024a"</span>)
|
|
assertThatJson(parsedJson).array(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['events']"</span>).contains(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['status']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"OK"</span>)
|
|
and:
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\$.events[0].operation"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".+"</span>)
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\$.events[0].eventId"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})\$"</span>)
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"\$.events[0].status"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".+"</span>)</pre><p>As you can see the assertion is malformed. That’s because only the first element of the array got asserted.
|
|
In order to fix this it’s best to apply the assertion to the whole <code class="literal">$.events</code> collection and assert it
|
|
via the <code class="literal">byCommand(…​)</code> method.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_jax_rs_support" href="#_jax_rs_support"></a>84.7 JAX-RS support</h2></div></div></div><p>We support JAX-RS 2 Client API. Base class needs to define <code class="literal">protected WebTarget webTarget</code> and server initialization, right now the only option how to test JAX-RS API is to start a web server.</p><p>Request with a body needs to have a content type set otherwise <code class="literal">application/octet-stream</code> is going to be used.</p><p>In order to use JAX-RS mode, use the following settings:</p><pre class="programlisting">testMode == <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'JAXRSCLIENT'</span></pre><p>Example of a test API generated:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
Response response = webTarget
|
|
.path(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/users"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"limit"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"10"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"offset"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"20"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"filter"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"email"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"sort"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"search"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"55"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"age"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"99"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Denis.Stepanov"</span>)
|
|
.queryParam(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"email"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bob@email.com"</span>)
|
|
.request()
|
|
.method(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"GET"</span>);
|
|
|
|
String responseAsString = response.readEntity(String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.getStatus()).isEqualTo(<span class="hl-number">200</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(responseAsString);
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"['property1']"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"a"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'</span></pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_async_support" href="#_async_support"></a>84.8 Async support</h2></div></div></div><p>If you’re using asynchronous communication on the server side (your controllers are returning
|
|
<code class="literal">Callable</code>, <code class="literal">DeferredResult</code> etc. then inside your contract you have to provide in the <code class="literal">response</code>
|
|
section a <code class="literal">async()</code> method. Example:</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method GET()
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/get'</span>
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Passed'</span>
|
|
async()
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_working_with_context_paths" href="#_working_with_context_paths"></a>84.9 Working with Context Paths</h2></div></div></div><p>Spring Cloud Contract supports context paths.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>The only thing that changes in order to fully support context paths is the switch
|
|
on the <span class="strong"><strong>PRODUCER</strong></span> side. The autogenerated tests need to be using the <span class="strong"><strong>EXPLICIT</strong></span> mode.</p></td></tr></table></div><p>The consumer side remains untouched, in order for the generated test to pass you have to switch the <span class="strong"><strong>EXPLICIT</strong></span> mode.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><extensions></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></extensions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><testMode></span>EXPLICIT<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></testMode></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">contracts {
|
|
testMode = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'EXPLICIT'</span>
|
|
}</pre><p class="secondary">
|
|
</p><p>That way you’ll generate a test that <span class="strong"><strong>DOES NOT</strong></span> use MockMvc. It means that you’re generating
|
|
real requests and you need to setup your generated test’s base class to work on a real socket.</p><p>Let’s imagine the following contract:</p><pre class="programlisting">org.springframework.cloud.contract.spec.Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'GET'</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/my-context-path/url'</span>
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
}</pre><p>Here is an example of how to set up a base class and Rest Assured for everything to work correctly.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.jayway.restassured.RestAssured;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.junit.Before;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.boot.context.embedded.LocalServerPort;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.boot.test.context.SpringBootTest;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(classes = ContextPathTestingBaseClass.class, webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ContextPathTestingBaseClass {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@LocalServerPort</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> port;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Before</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> setup() {
|
|
RestAssured.baseURI = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://localhost"</span>;
|
|
RestAssured.port = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.port;
|
|
}
|
|
}</pre><p>That way all:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">all your requests in the autogenerated tests will be sent to the real endpoint with your context path included (e.g. <code class="literal">/my-context-path/url</code>)</li><li class="listitem">your contracts reflect that you have a context path, thus your generated stubs will also
|
|
have that information (e.g. in the stubs you’ll see that you have too call <code class="literal">/my-context-path/url</code>)</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_messaging_top_level_elements" href="#_messaging_top_level_elements"></a>84.10 Messaging Top-Level Elements</h2></div></div></div><p>The DSL for messaging looks a little bit different than the one that focuses on HTTP.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_output_triggered_by_a_method" href="#_output_triggered_by_a_method"></a>84.10.1 Output triggered by a method</h3></div></div></div><p>The output message can be triggered by calling a method (e.g. a Scheduler was started and a message was sent)</p><pre class="programlisting">def dsl = Contract.make {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Human readable description</span>
|
|
description <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Some description'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Label by means of which the output message can be triggered</span>
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'some_label'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// input to the contract</span>
|
|
input {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the contract will be triggered by a method</span>
|
|
triggeredBy(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'bookReturnedTriggered()'</span>)
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// output message of the contract</span>
|
|
outputMessage {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// destination to which the output message will be sent</span>
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'output'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the body of the output message</span>
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'{ "bookName" : "foo" }'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the headers of the output message</span>
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
}
|
|
}
|
|
}</pre><p>In this case the output message will be sent to <code class="literal">output</code> if a method called <code class="literal">bookReturnedTriggered</code> will be executed. In the message <span class="strong"><strong>publisher’s</strong></span> side
|
|
we will generate a test that will call that method to trigger the message. On the <span class="strong"><strong>consumer</strong></span> side you can use the <code class="literal">some_label</code> to trigger the message.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_output_triggered_by_a_message" href="#_output_triggered_by_a_message"></a>84.10.2 Output triggered by a message</h3></div></div></div><p>The output message can be triggered by receiving a message.</p><pre class="programlisting">def dsl = Contract.make {
|
|
description <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Some Description'</span>
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'some_label'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// input is a message</span>
|
|
input {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// the message was received from this destination</span>
|
|
messageFrom(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'input'</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// has the following body</span>
|
|
messageBody([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and the following headers</span>
|
|
messageHeaders {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>)
|
|
}
|
|
}
|
|
outputMessage {
|
|
sentTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'output'</span>)
|
|
body([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'BOOK-NAME'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>)
|
|
}
|
|
}
|
|
}</pre><p>In this case the output message will be sent to <code class="literal">output</code> if a proper message will be received on the <code class="literal">input</code> destination. In the message <span class="strong"><strong>publisher’s</strong></span> side
|
|
we will generate a test that will send the input message to the defined destination. On the <span class="strong"><strong>consumer</strong></span> side you can either send a message to the input
|
|
destination or use the <code class="literal">some_label</code> to trigger the message.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_consumer_producer" href="#_consumer_producer"></a>84.10.3 Consumer / Producer</h3></div></div></div><p>In HTTP you have a notion of <code class="literal">client</code>/<code class="literal">stub and `server</code>/<code class="literal">test</code> notation. You can use them also in messaging but we’re providing also the <code class="literal">consumer</code> and <code class="literal">produer</code> methods
|
|
as presented below (note you can use either <code class="literal">$</code> or <code class="literal">value</code> methods to provide <code class="literal">consumer</code> and <code class="literal">producer</code> parts)</p><pre class="programlisting">Contract.make {
|
|
label <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'some_label'</span>
|
|
input {
|
|
messageFrom value(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:input'</span>))
|
|
messageBody([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
messageHeaders {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'sample'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'header'</span>)
|
|
}
|
|
}
|
|
outputMessage {
|
|
sentTo $(consumer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:input'</span>), producer(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'jms:output'</span>))
|
|
body([
|
|
bookName: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'foo'</span>
|
|
])
|
|
}
|
|
}</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_multiple_contracts_in_one_file" href="#_multiple_contracts_in_one_file"></a>84.11 Multiple contracts in one file</h2></div></div></div><p>It’s possible to define multiple contracts in one file. An example of such a contract can look like this</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.Contract
|
|
|
|
[
|
|
Contract.make {
|
|
name(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"should post a user"</span>)
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'POST'</span>
|
|
url(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/users/1'</span>)
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
},
|
|
Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'POST'</span>
|
|
url(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/users/2'</span>)
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
}
|
|
}
|
|
]</pre><p>In this example one contract has the <code class="literal">name</code> field and the other doesn’t. This will lead to generation of
|
|
two tests that will look more or less like this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.verifier.tests.com.hello;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.example.TestBase;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.jayway.jsonpath.DocumentContext;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.jayway.jsonpath.JsonPath;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.jayway.restassured.module.mockmvc.specification.MockMvcRequestSpecification;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.jayway.restassured.response.ResponseOptions;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.junit.Test;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> com.jayway.restassured.module.mockmvc.RestAssuredMockMvc.*;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> org.assertj.core.api.Assertions.assertThat;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> V1Test <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> TestBase {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> validate_should_post_a_user() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/users/1"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> validate_withList_<span class="hl-number">1</span>() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given();
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/users/2"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);
|
|
}
|
|
|
|
}</pre><p>Notice that for the contract that has the <code class="literal">name</code> field the generated test method is named
|
|
<code class="literal">validate_should_post_a_user</code>. For the one that doesn’t have the name it’s called
|
|
<code class="literal">validate_withList_1</code>. It corresponds to the name of the file <code class="literal">WithList.groovy</code> and the
|
|
index of the contract in the list.</p><p>The generated stubs will look like this</p><pre class="screen">should post a user.json
|
|
1_WithList.json</pre><p>As you can see the first file got the <code class="literal">name</code> parameter from the contract. The second
|
|
got the name of the contract file <code class="literal">WithList.groovy</code> prefixed with the index (in this case
|
|
contract had index <code class="literal">1</code> in the list of contracts in the file).</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>As you can see it’s much better if you name your contracts since then your tests
|
|
are far more meaningful.</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_customization" href="#_customization"></a>85. Customization</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_extending_the_dsl" href="#_extending_the_dsl"></a>85.1 Extending the DSL</h2></div></div></div><p>It is possible to provide your own functions to the DSL. The key requirement for this
|
|
feature was to maintain the static compatibility. Below you will be able to see an example
|
|
of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">creation of a JAR with reusable classes</li><li class="listitem">referencing of these classes in the DSLs</li></ul></div><p>The full example can be found <a class="link" href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples" target="_top">here</a>.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_common_jar" href="#_common_jar"></a>85.1.1 Common JAR</h3></div></div></div><p>Below you can find three classes that we will reuse in the DSLs.</p><p><span class="strong"><strong>PatternUtils</strong></span> contains functions used by both the <span class="strong"><strong>consumer</strong></span> and the <span class="strong"><strong>producer</strong></span>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.example;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> java.util.regex.Pattern;
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* If you want to use {@link Pattern} directly in your tests
|
|
* then you can create a class resembling this one. It can
|
|
* contain all the {@link Pattern} you want to use in the DSL.
|
|
*
|
|
* <pre>
|
|
* {@code
|
|
* request {
|
|
* body(
|
|
* [ age: $(c(PatternUtils.oldEnough()))]
|
|
* )
|
|
* }
|
|
* </pre>
|
|
*
|
|
* Notice that we're using both {@code $()} for dynamic values
|
|
* and {@code c()} for the consumer side.
|
|
*
|
|
* @author Marcin Grzejszczak
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//tag::impl[]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> PatternUtils {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> String tooYoung() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::start[]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[0-1][0-9]"</span>;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::end[return]</span>
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> Pattern oldEnough() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::start[]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[2-9][0-9]"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::end[return]</span>
|
|
}
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Makes little sense but it's just an example ;)
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> Pattern ok() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::start[]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> Pattern.compile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"OK"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::end[return]</span>
|
|
}
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//end::impl[]</span></pre><p><span class="strong"><strong>ConsumerUtils</strong></span> contains functions used by the <span class="strong"><strong>consumer</strong></span>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.example;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.internal.ClientDslProperty;
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* DSL Properties passed to the DSL from the consumer's perspective.
|
|
* That means that on the input side {@code Request} for HTTP
|
|
* or {@code Input} for messaging you can have a regular expression.
|
|
* On the {@code Response} for HTTP or {@code Output} for messaging
|
|
* you have to have a concrete value.
|
|
*
|
|
* @author Marcin Grzejszczak
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//tag::impl[]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ConsumerUtils {
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Consumer side property. By using the {@link ClientDslProperty}
|
|
* you can omit most of boilerplate code from the perspective
|
|
* of dynamic values. Example
|
|
*
|
|
* <pre>
|
|
* {@code
|
|
* request {
|
|
* body(
|
|
* [ age: $(ConsumerUtils.oldEnough())]
|
|
* )
|
|
* }
|
|
* </pre>
|
|
*
|
|
* That way it's in the implementation that we decide what value we will pass to the consumer
|
|
* and which one to the producer.
|
|
*
|
|
* @author Marcin Grzejszczak
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> ClientDslProperty oldEnough() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::start[]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// this example is not the best one and</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// theoretically you could just pass the regex instead of `ServerDslProperty` but</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// it's just to show some new tricks :)</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ClientDslProperty(PatternUtils.oldEnough(), <span class="hl-number">40</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//remove::end[return]</span>
|
|
}
|
|
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//end::impl[]</span></pre><p><span class="strong"><strong>ProducerUtils</strong></span> contains functions used by the <span class="strong"><strong>producer</strong></span>.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.example;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.internal.ServerDslProperty;
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* DSL Properties passed to the DSL from the producer's perspective.
|
|
* That means that on the input side {@code Request} for HTTP
|
|
* or {@code Input} for messaging you have to have a concrete value.
|
|
* On the {@code Response} for HTTP or {@code Output} for messaging
|
|
* you can have a regular expression.
|
|
*
|
|
* @author Marcin Grzejszczak
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//tag::impl[]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ProducerUtils {
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Producer side property. By using the {@link ProducerUtils}
|
|
* you can omit most of boilerplate code from the perspective
|
|
* of dynamic values. Example
|
|
*
|
|
* <pre>
|
|
* {@code
|
|
* response {
|
|
* body(
|
|
* [ status: $(ProducerUtils.ok())]
|
|
* )
|
|
* }
|
|
* </pre>
|
|
*
|
|
* That way it's in the implementation that we decide what value we will pass to the consumer
|
|
* and which one to the producer.
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> ServerDslProperty ok() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// this example is not the best one and</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// theoretically you could just pass the regex instead of `ServerDslProperty` but</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// it's just to show some new tricks :)</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ServerDslProperty( PatternUtils.ok(), <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"OK"</span>);
|
|
}
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">//end::impl[]</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_adding_the_dependency_to_project" href="#_adding_the_dependency_to_project"></a>85.1.2 Adding the dependency to project</h3></div></div></div><p>In order for the plugins and IDE to be able to reference the common JAR classes you need
|
|
to pass the dependency to your project.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_test_dependency_in_project_s_dependencies" href="#_test_dependency_in_project_s_dependencies"></a>85.1.3 Test dependency in project’s dependencies</h3></div></div></div><p>First add the common jar dependency as a test dependency. That way since your
|
|
contracts files are available at test resources path, automatically the
|
|
common jar classes will be visible in your Groovy files.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>com.example<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>beer-common<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${project.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">testCompile(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example:beer-common:0.0.1-SNAPSHOT"</span>)</pre><p class="secondary">
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_test_dependency_in_plugin_s_dependencies" href="#_test_dependency_in_plugin_s_dependencies"></a>85.1.4 Test dependency in plugin’s dependencies</h3></div></div></div><p>Now you have to add the dependency for the plugin to reuse at runtime.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><extensions></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></extensions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>com.example<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassMappings></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassMapping></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><contractPackageRegex></span>.*intoxication.*<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></contractPackageRegex></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassFQN></span>com.example.intoxication.BeerIntoxicationBase<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassFQN></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassMapping></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassMappings></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>com.example<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>beer-common<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${project.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>compile<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example:beer-common:0.0.1-SNAPSHOT"</span></pre><p class="secondary">
|
|
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_referencing_classes_in_dsls" href="#_referencing_classes_in_dsls"></a>85.1.5 Referencing classes in DSLs</h3></div></div></div><p>Now you can reference your classes in your DSL. Example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> contracts.beer.rest
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.example.ConsumerUtils
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.example.ProducerUtils
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.Contract
|
|
|
|
Contract.make {
|
|
description(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"
|
|
</span>Represents a successful scenario of getting a beer
|
|
|
|
```
|
|
given:
|
|
client is old enough
|
|
when:
|
|
he applies <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">for</span> a beer
|
|
then:
|
|
we<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'ll grant him the beer
|
|
</span>```
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">")
|
|
</span> request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'POST'</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/check'</span>
|
|
body(
|
|
age: $(ConsumerUtils.oldEnough())
|
|
)
|
|
headers {
|
|
contentType(applicationJson())
|
|
}
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"
|
|
</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${value(ProducerUtils.ok())}"</span>
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">")
|
|
</span> headers {
|
|
contentType(applicationJson())
|
|
}
|
|
}
|
|
}</pre></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_pluggable_architecture" href="#_pluggable_architecture"></a>86. Pluggable architecture</h2></div></div></div><p>There are cases where you have your contracts defined in other formats
|
|
like YAML, RAML or PACT. On the other hand you’d like to profit from
|
|
the test and stubs generation. It’s really easy to add your own implementation
|
|
of either of those. Also you can customize the way tests are generated (for example you can generate
|
|
tests for other languages) and you can do the same for stubs generation (you can generate
|
|
stubs for other stub http server implementations).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_contract_converter" href="#_custom_contract_converter"></a>86.1 Custom contract converter</h2></div></div></div><p>Let’s assume that your contract is written in a YAML file like this:</p><pre class="programlisting">request:
|
|
url: /foo
|
|
method: PUT
|
|
headers:
|
|
foo: bar
|
|
body:
|
|
foo: bar
|
|
response:
|
|
status: 200
|
|
headers:
|
|
foo2: bar
|
|
body:
|
|
foo2: bar</pre><p>Thanks to the interface</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.spec
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Converter to be used to convert FROM {@link File} TO {@link Contract}
|
|
* and from {@link Contract} to {@code T}
|
|
*
|
|
* @param <T> - type to which we want to convert the contract
|
|
*
|
|
* @author Marcin Grzejszczak
|
|
* @since 1.1.0
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> ContractConverter<T> {
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Should this file be accepted by the converter. Can use the file extension
|
|
* to check if the conversion is possible.
|
|
*
|
|
* @param file - file to be considered for conversion
|
|
* @return - {@code true} if the given implementation can convert the file
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> isAccepted(File file)
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Converts the given {@link File} to its {@link Contract} representation
|
|
*
|
|
* @param file - file to convert
|
|
* @return - {@link Contract} representation of the file
|
|
*/</strong>
|
|
Collection<Contract> convertFrom(File file)
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Converts the given {@link Contract} to a {@link T} representation
|
|
*
|
|
* @param contract - the parsed contract
|
|
* @return - {@link T} the type to which we do the conversion
|
|
*/</strong>
|
|
T convertTo(Collection<Contract> contract)
|
|
}</pre><p>you can register your own implementation of a contract structure converter.
|
|
Your implementation needs to state the condition on which it should start the
|
|
conversion. Also you have to define how to perform that conversion in both ways.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>Once you create your implementation you have to create a <code class="literal">/META-INF/spring.factories</code>
|
|
file in which you provide the fully qualified name of your implementation.</p></td></tr></table></div><p>Example of a <code class="literal">spring.factories</code> file</p><pre class="screen"># Converters
|
|
org.springframework.cloud.contract.spec.ContractConverter=\
|
|
org.springframework.cloud.contract.verifier.converter.YamlContractConverter</pre><p>and the YAML implementation</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.verifier.converter
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> java.nio.file.Files
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> groovy.transform.CompileStatic
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.Contract
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.ContractConverter
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.internal.Headers
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.yaml.snakeyaml.Yaml
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Simple converter from and to a {@link YamlContract} to a collection of {@link Contract}
|
|
*/</strong>
|
|
<em><span class="hl-annotation" style="color: gray">@CompileStatic</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> YamlContractConverter <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> ContractConverter<List<YamlContract>> {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> isAccepted(File file) {
|
|
String name = file.getName()
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> name.endsWith(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".yml"</span>) || name.endsWith(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".yaml"</span>)
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Collection<Contract> convertFrom(File file) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
YamlContract yamlContract = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> Yaml().loadAs(
|
|
Files.newInputStream(file.toPath()), YamlContract.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> [Contract.make {
|
|
request {
|
|
method(yamlContract?.request?.method)
|
|
url(yamlContract?.request?.url)
|
|
headers {
|
|
yamlContract?.request?.headers?.each { String key, Object value ->
|
|
header(key, value)
|
|
}
|
|
}
|
|
body(yamlContract?.request?.body)
|
|
}
|
|
response {
|
|
status(yamlContract?.response?.status)
|
|
headers {
|
|
yamlContract?.response?.headers?.each { String key, Object value ->
|
|
header(key, value)
|
|
}
|
|
}
|
|
body(yamlContract?.response?.body)
|
|
}
|
|
}]
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">catch</span> (FileNotFoundException e) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throw</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> IllegalStateException(e)
|
|
}
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> List<YamlContract> convertTo(Collection<Contract> contracts) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> contracts.collect { Contract contract ->
|
|
YamlContract yamlContract = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> YamlContract()
|
|
yamlContract.request.with {
|
|
method = contract?.request?.method?.clientValue
|
|
url = contract?.request?.url?.clientValue
|
|
headers = (contract?.request?.headers as Headers)?.asStubSideMap()
|
|
body = contract?.request?.body?.clientValue as Map
|
|
}
|
|
yamlContract.response.with {
|
|
status = contract?.response?.status?.clientValue as Integer
|
|
headers = (contract?.response?.headers as Headers)?.asStubSideMap()
|
|
body = contract?.response?.body?.clientValue as Map
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> yamlContract
|
|
}
|
|
}
|
|
}</pre><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_pact_converter" href="#_pact_converter"></a>86.1.1 Pact converter</h3></div></div></div><p>Spring Cloud Contract comes with an out of the box support for <a class="link" href="https://docs.pact.io/" target="_top">Pact</a> representation of contracts.
|
|
In other words instead of using the Groovy DSL you can use Pact files. In this section
|
|
we will present how to add such a support for your project.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_pact_contract" href="#_pact_contract"></a>86.1.2 Pact contract</h3></div></div></div><p>We will be working on the following example of a Pact contract. We’ve placed this file under
|
|
the <code class="literal">src/test/resources/contracts</code> folder.</p><pre class="programlisting">{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"provider"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Provider"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"consumer"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"name"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Consumer"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"interactions"</span>: [
|
|
{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"description"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">""</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"PUT"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"path"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/fraudcheck"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"clientId"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"1234567890"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"loanAmount"</span>: <span class="hl-number">99999</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchingRules"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.body.clientId"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"match"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"regex"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"regex"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"[0-9]{10}"</span>
|
|
}
|
|
}
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span>: <span class="hl-number">200</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json;charset=UTF-8"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"fraudCheckStatus"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"FRAUD"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"rejectionReason"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Amount too high"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchingRules"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.body.fraudCheckStatus"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"match"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"regex"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"regex"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"FRAUD"</span>
|
|
}
|
|
}
|
|
}
|
|
}
|
|
],
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"metadata"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"pact-specification"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"version"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2.0.0"</span>
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"pact-jvm"</span>: {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"version"</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"2.4.18"</span>
|
|
}
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_pact_for_producers" href="#_pact_for_producers"></a>86.1.3 Pact for producers</h3></div></div></div><p>On the producer side you have add to your plugin configuration two additional dependencies.
|
|
One is the Spring Cloud Contract Pact support and the other represents the current
|
|
Pact version that you’re using.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><extensions></span>true<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></extensions></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>com.example.fraud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-spec-pact<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>au.com.dius<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>pact-jvm-model<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>2.4.18<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-contract-spec-pact:${findProperty('verifierVersion') ?: verifierVersion}"</span>
|
|
classpath <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'au.com.dius:pact-jvm-model:2.4.18'</span></pre><p class="secondary">
|
|
</p><p>When you execute the build of your application a test, looking more or less like this, will be generated</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> validate_shouldMarkClientAsFraud() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// given:</span>
|
|
MockMvcRequestSpecification request = given()
|
|
.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json"</span>)
|
|
.body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"clientId\":\"1234567890\",\"loanAmount\":99999}"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// when:</span>
|
|
ResponseOptions response = given().spec(request)
|
|
.put(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/fraudcheck"</span>);
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then:</span>
|
|
assertThat(response.statusCode()).isEqualTo(<span class="hl-number">200</span>);
|
|
assertThat(response.header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>)).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json;charset=UTF-8"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
|
|
assertThatJson(parsedJson).field(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"rejectionReason"</span>).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Amount too high"</span>);
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// and:</span>
|
|
assertThat(parsedJson.read(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.fraudCheckStatus"</span>, String.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>)).matches(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"FRAUD"</span>);
|
|
}</pre><p>and the stub looking like this</p><pre class="programlisting">{
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"uuid"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"996ae5ae-6834-4db6-8fac-358ca187ab62"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/fraudcheck"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"PUT"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"equalTo"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json"</span>
|
|
}
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bodyPatterns"</span> : [ {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.loanAmount == 99999)]"</span>
|
|
}, {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.clientId =~ /([0-9]{10})/)]"</span>
|
|
} ]
|
|
},
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span> : <span class="hl-number">200</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"fraudCheckStatus\":\"FRAUD\",\"rejectionReason\":\"Amount too high\"}"</span>,
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/vnd.fraud.v1+json;charset=UTF-8"</span>
|
|
}
|
|
}
|
|
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_pact_for_consumers" href="#_pact_for_consumers"></a>86.1.4 Pact for consumers</h3></div></div></div><p>On the producer side you have add to your project dependencies two additional dependencies.
|
|
One is the Spring Cloud Contract Pact support and the other represents the current
|
|
Pact version that you’re using.</p><p class="primary"><b>Maven. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-spec-pact<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>au.com.dius<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>pact-jvm-model<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>2.4.18<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span></pre><p class="primary">
|
|
</p><p class="secondary"><b>Gradle. </b>
|
|
</p><pre class="programlisting">testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"org.springframework.cloud:spring-cloud-contract-spec-pact"</span>
|
|
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'au.com.dius:pact-jvm-model:2.4.18'</span></pre><p class="secondary">
|
|
</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_test_generator" href="#_custom_test_generator"></a>86.2 Custom test generator</h2></div></div></div><p>If you want to generate tests for different languages than Java or you’re
|
|
not happy with the way we’re building Java tests for you then you can register
|
|
your own implementation to do that.</p><p>Thanks to the interface</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.verifier.builder
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.verifier.config.ContractVerifierConfigProperties
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.verifier.file.ContractMetadata
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Builds a single test.
|
|
*
|
|
* @since 1.1.0
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> SingleTestGenerator {
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Creates contents of a single test class in which all test scenarios from
|
|
* the contract metadata should be placed.
|
|
*
|
|
* @param properties - properties passed to the plugin
|
|
* @param listOfFiles - list of parsed contracts with additional metadata
|
|
* @param className - the name of the generated test class
|
|
* @param classPackage - the name of the package in which the test class should be stored
|
|
* @param includedDirectoryRelativePath - relative path to the included directory
|
|
* @return contents of a single test class
|
|
*/</strong>
|
|
String buildClass(ContractVerifierConfigProperties properties, Collection<ContractMetadata> listOfFiles,
|
|
String className, String classPackage, String includedDirectoryRelativePath)
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Extension that should be appended to the generated test class. E.g. {@code .java} or {@code .php}
|
|
*
|
|
* @param properties - properties passed to the plugin
|
|
*/</strong>
|
|
String fileExtension(ContractVerifierConfigProperties properties)
|
|
}</pre><p>you can register your own implementation that generates a test. Again, it’s enough to provide
|
|
a proper <code class="literal">spring.factories</code> file. Example:</p><pre class="screen">org.springframework.cloud.contract.verifier.builder.SingleTestGenerator=/
|
|
com.example.MyGenerator</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_stub_generator" href="#_custom_stub_generator"></a>86.3 Custom stub generator</h2></div></div></div><p>If you want to generate stubs for other stub server than WireMock it’s enough to
|
|
plug in your own implementation of this interface:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.verifier.converter
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> groovy.transform.CompileStatic
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.Contract
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.verifier.file.ContractMetadata
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Converts contracts into their stub representation.
|
|
*
|
|
* @since 1.1.0
|
|
*/</strong>
|
|
<em><span class="hl-annotation" style="color: gray">@CompileStatic</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">interface</span> StubGenerator {
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Returns {@code true} if the converter can handle the file to convert it into a stub.
|
|
*/</strong>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> canHandleFileName(String fileName)
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Returns the collection of converted contracts into stubs. One contract can
|
|
* result in multiple stubs.
|
|
*/</strong>
|
|
Map<Contract, String> convertContents(String rootName, ContractMetadata content)
|
|
|
|
<strong class="hl-tag" style="color: blue">/**
|
|
* Returns the name of the converted stub file. If you have multiple contracts
|
|
* in a single file then a prefix will be added to the generated file. If you
|
|
* provide the {@link Contract#name} field then that field will override the
|
|
* generated file name.
|
|
*
|
|
* Example: name of file with 2 contracts is {@code foo.groovy}, it will be
|
|
* converted by the implementation to {@code foo.json}. The recursive file
|
|
* converter will create two files {@code 0_foo.json} and {@code 1_foo.json}
|
|
*/</strong>
|
|
String generateOutputFileNameForInput(String inputFileName)
|
|
}</pre><p>you can register your own implementation that generate Stubs. Again, it’s enough to provide
|
|
a proper <code class="literal">spring.factories</code> file. Example:</p><pre class="screen"># Stub converters
|
|
org.springframework.cloud.contract.verifier.converter.StubGenerator=\
|
|
org.springframework.cloud.contract.verifier.wiremock.DslToWireMockClientConverter</pre><p>The default implementation is the WireMock stub generation.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>You can provide multiple stub generator implementations. That way for example from a single
|
|
DSL as input you can e.g. produce WireMock stubs and Pact files too!</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_stub_runner" href="#_custom_stub_runner"></a>86.4 Custom Stub Runner</h2></div></div></div><p>If you decide to have a custom stub generation you also need a custom way of running
|
|
stubs with your different stub provider.</p><p>Let us assume that you’re using <a class="link" href="https://github.com/dreamhead/moco" target="_top">Moco</a> to build your stubs.
|
|
You wrote a proper stub generator and your stubs got placed in a JAR file.</p><p>In order for Stub Runner to know how to run your stubs you have to define a custom
|
|
HTTP Stub server implementation. It can look like this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.springframework.cloud.contract.stubrunner.provider.moco
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.github.dreamhead.moco.bootstrap.arg.HttpArgs
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.github.dreamhead.moco.runner.JsonRunner
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.github.dreamhead.moco.runner.RunnerSetting
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> groovy.util.logging.Slf4j
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.stubrunner.HttpServerStub
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.util.SocketUtils
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Slf4j</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> MocoHttpServerStub <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> HttpServerStub {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> started
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> JsonRunner runner
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> port
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> port() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (!isRunning()) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> -<span class="hl-number">1</span>
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> port
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> isRunning() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> started
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
HttpServerStub start() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> start(SocketUtils.findAvailableTcpPort())
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
HttpServerStub start(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">int</span> port) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.port = port
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
HttpServerStub stop() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">if</span> (!isRunning()) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>
|
|
}
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.runner.stop()
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
HttpServerStub registerMappings(Collection<File> stubFiles) {
|
|
List<RunnerSetting> settings = stubFiles.findAll { it.name.endsWith(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"json"</span>) }
|
|
.collect {
|
|
log.info(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Trying to parse [{}]"</span>, it.name)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">try</span> {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> RunnerSetting.aRunnerSetting().withStream(it.newInputStream()).build()
|
|
} <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">catch</span> (Exception e) {
|
|
log.warn(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Exception occurred while trying to parse file [{}]"</span>, it.name, e)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> null
|
|
}
|
|
}.findAll { it }
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.runner = JsonRunner.newJsonRunnerWithSetting(settings,
|
|
HttpArgs.httpArgs().withPort(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.port).build())
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.runner.run()
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.started = true
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>
|
|
}
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">boolean</span> isAccepted(File file) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> file.name.endsWith(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">".json"</span>)
|
|
}
|
|
}</pre><p>and just register it in your <code class="literal">spring.factories</code> file</p><pre class="screen">org.springframework.cloud.contract.stubrunner.HttpServerStub=\
|
|
org.springframework.cloud.contract.stubrunner.provider.moco.MocoHttpServerStub</pre><p>that way you’ll be able to run stubs using Moco.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you don’t provide any implementation then the default one - WireMock based
|
|
will be picked. If you provide more than one then the first one on the list will be picked.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_custom_stub_downloader" href="#_custom_stub_downloader"></a>86.5 Custom Stub Downloader</h2></div></div></div><p>You can customize the way your stubs are downloaded. It’s enough to create an
|
|
implementation of the <code class="literal">StubDownloaderBuilder</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> com.example;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> CustomStubDownloaderBuilder <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">implements</span> StubDownloaderBuilder {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> StubDownloader build(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">final</span> StubRunnerOptions stubRunnerOptions) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> StubDownloader() {
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> Map.Entry<StubConfiguration, File> downloadAndUnpackStubJar(
|
|
StubConfiguration config) {
|
|
File unpackedStubs = retrieveStubs();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> AbstractMap.SimpleEntry<>(
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> StubConfiguration(config.getGroupId(), config.getArtifactId(), version,
|
|
config.getClassifier()), unpackedStubs);
|
|
}
|
|
|
|
File retrieveStubs() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// here goes your custom logic to provide a folder where all the stubs reside</span>
|
|
}
|
|
}</pre><p>and just register it in your <code class="literal">spring.factories</code> file</p><pre class="screen"># Example of a custom Stub Downloader Provider
|
|
org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder=\
|
|
com.example.CustomStubDownloaderBuilder</pre><p>that way you’ll be able to pick a folder with the source of your stubs.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>If you don’t provide any implementation then the default one will be picked.
|
|
If you provide <code class="literal">repositoryRoot</code> property or <code class="literal">workOffline</code> flag then Aether based
|
|
that will download stubs from a remote repo will be picked. If you don’t provide these
|
|
values then the <code class="literal">ClasspathStubProvider</code> will be picked that will scan the classpath.
|
|
If you provide more than one, then the first one on the list will be picked.</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_spring_cloud_contract_wiremock" href="#_spring_cloud_contract_wiremock"></a>87. Spring Cloud Contract WireMock</h2></div></div></div><p>Modules giving you the possibility to use
|
|
<a class="link" href="http://wiremock.org" target="_top">WireMock</a> with different servers by using the
|
|
"ambient" server embedded in a Spring Boot application. Check out the
|
|
<a class="link" href="https://github.com/spring-cloud/spring-cloud-contract/tree/1.0.x/samples" target="_top">samples</a>
|
|
for more details.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/important.png"></td><th align="left">Important</th></tr><tr><td align="left" valign="top"><p>The Spring Cloud Release Train BOM imports <code class="literal">spring-cloud-contract-dependencies</code>
|
|
which in turn has exclusions for the dependencies needed by WireMock. This might lead to a situation that
|
|
even if you’re not using Spring Cloud Contract then your dependencies will be influenced
|
|
anyways.</p></td></tr></table></div><p>If you have a Spring Boot application that uses Tomcat as an embedded
|
|
server, for example (the default with <code class="literal">spring-boot-starter-web</code>), then
|
|
you can simply add <code class="literal">spring-cloud-contract-wiremock</code> to your classpath
|
|
and add <code class="literal">@AutoConfigureWireMock</code> in order to be able to use Wiremock
|
|
in your tests. Wiremock runs as a stub server and you can register
|
|
stub behaviour using a Java API or via static JSON declarations as
|
|
part of your test. Here’s a simple example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureWireMock(port = 0)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> WiremockForDocsTests {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// A service that calls out over HTTP</span>
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> Service service;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Using the WireMock APIs in the normal way:</span>
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> contextLoads() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Stubbing WireMock</span>
|
|
stubFor(get(urlEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/resource"</span>))
|
|
.willReturn(aResponse().withHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"text/plain"</span>).withBody(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World!"</span>)));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// We're asserting if WireMock responded properly</span>
|
|
assertThat(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.service.go()).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World!"</span>);
|
|
}
|
|
|
|
}</pre><p>To start the stub server on a different port use <code class="literal">@AutoConfigureWireMock(port=9999)</code> (for example), and for a random port use the value 0. The stub server port will be bindable in the test application context as "wiremock.server.port". Using <code class="literal">@AutoConfigureWireMock</code> adds a bean of type <code class="literal">WiremockConfiguration</code> to your test application context, where it will be cached in between methods and classes having the same context, just like for normal Spring integration tests.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_registering_stubs_automatically" href="#_registering_stubs_automatically"></a>87.1 Registering Stubs Automatically</h2></div></div></div><p>If you use <code class="literal">@AutoConfigureWireMock</code> then it will register WireMock
|
|
JSON stubs from the file system or classpath, by default from
|
|
<code class="literal">file:src/test/resources/mappings</code>. You can customize the locations
|
|
using the <code class="literal">stubs</code> attribute in the annotation, which can be a resource
|
|
pattern (ant-style) or a directory, in which case <code class="literal"><span class="strong"><strong>*/</strong></span>.json</code> is
|
|
appended. Example:</p><pre class="screen">@RunWith(SpringRunner.class)
|
|
@SpringBootTest
|
|
@AutoConfigureWireMock(stubs="classpath:/stubs")
|
|
public class WiremockImportApplicationTests {
|
|
|
|
@Autowired
|
|
private Service service;
|
|
|
|
@Test
|
|
public void contextLoads() throws Exception {
|
|
assertThat(this.service.go()).isEqualTo("Hello World!");
|
|
}
|
|
|
|
}</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Actually WireMock always loads mappings from
|
|
<code class="literal">src/test/resources/mappings</code> <span class="strong"><strong>as well as</strong></span> the custom locations in the
|
|
stubs attribute. To change this behaviour you have to also specify a
|
|
files root as described next.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_files_to_specify_the_stub_bodies" href="#_using_files_to_specify_the_stub_bodies"></a>87.2 Using Files to Specify the Stub Bodies</h2></div></div></div><p>WireMock can read response bodies from files on the classpath or file
|
|
system. In that case you will see in the JSON DSL that the response
|
|
has a "bodyFileName" instead of a (literal) "body". The files are
|
|
resolved relative to a root directory <code class="literal">src/test/resources/__files</code> by
|
|
default. To customize this location you can set the <code class="literal">files</code> attribute
|
|
in the <code class="literal">@AutoConfigureWireMock</code> annotation to the location of the
|
|
parent directory (i.e. the place <code class="literal">__files</code> is a
|
|
subdirectory). You can use Spring resource notation to refer to
|
|
<code class="literal">file:…​</code> or <code class="literal">classpath:…​</code> locations (but generic URLs are not
|
|
supported). A list of values can be given and WireMock will resolve
|
|
the first file that exists when it needs to find a response body.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>when you configure the <code class="literal">files</code> root, then it affects the
|
|
automatic loading of stubs as well (they come from the root location
|
|
in a subdirectory called "mappings"). The value of <code class="literal">files</code> has no
|
|
effect on the stubs loaded explicitly from the <code class="literal">stubs</code> attribute.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_alternative_using_junit_rules" href="#_alternative_using_junit_rules"></a>87.3 Alternative: Using JUnit Rules</h2></div></div></div><p>For a more conventional WireMock experience, using JUnit <code class="literal">@Rules</code> to
|
|
start and stop the server, just use the <code class="literal">WireMockSpring</code> convenience
|
|
class to obtain an <code class="literal">Options</code> instance:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> WiremockForDocsClassRuleTests {
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Start WireMock on some dynamic port</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// for some reason `dynamicPort()` is not working properly</span>
|
|
<em><span class="hl-annotation" style="color: gray">@ClassRule</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> WireMockClassRule wiremock = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> WireMockClassRule(
|
|
WireMockSpring.options().dynamicPort());
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// A service that calls out over HTTP to localhost:${wiremock.port}</span>
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> Service service;
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Using the WireMock APIs in the normal way:</span>
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> contextLoads() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// Stubbing WireMock</span>
|
|
wiremock.stubFor(get(urlEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/resource"</span>))
|
|
.willReturn(aResponse().withHeader(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"text/plain"</span>).withBody(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World!"</span>)));
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// We're asserting if WireMock responded properly</span>
|
|
assertThat(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.service.go()).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World!"</span>);
|
|
}
|
|
|
|
}</pre><p>The use <code class="literal">@ClassRule</code> means that the server will shut down after all the methods in this class.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_relaxed_ssl_validation_for_rest_template" href="#_relaxed_ssl_validation_for_rest_template"></a>87.4 Relaxed SSL Validation for Rest Template</h2></div></div></div><p>WireMock allows you to stub a "secure" server with an "https" URL protocol. If your application wants to
|
|
contact that stub server in an integration test, then it will find that the SSL certificates are not
|
|
valid (it’s the usual problem with self-installed certificates). The best option is often to just
|
|
re-configure the client to use "http", but if that’s not open to you then you can ask Spring to configure
|
|
an HTTP client that ignores SSL validation errors (just for tests).</p><p>To make this work with minimum fuss you need to be using the Spring Boot <code class="literal">RestTemplateBuilder</code> in your app,
|
|
e.g.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Bean</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> RestTemplate restTemplate(RestTemplateBuilder builder) {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> builder.build();
|
|
}</pre><p>This is because the builder is passed through callbacks to initalize it, so the SSL validation can be set up
|
|
in the client at that point. This will happen automatically in your test if you are using the
|
|
<code class="literal">@AutoConfigureWireMock</code> annotation (or the stub runner). If you are using the JUnit <code class="literal">@Rule</code> approach you need
|
|
to add the <code class="literal">@AutoConfigureHttpClient</code> annotation as well:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest("app.baseUrl=https://localhost:6443")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureHttpClient</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> WiremockHttpsServerApplicationTests {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@ClassRule</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> WireMockClassRule wiremock = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> WireMockClassRule(
|
|
WireMockSpring.options().httpsPort(<span class="hl-number">6443</span>));
|
|
...
|
|
}</pre><p>If you are using <code class="literal">spring-boot-starter-test</code> then you will have the Apache HTTP client on the classpath and it will
|
|
be selected by the <code class="literal">RestTemplateBuilder</code> and configured to ignore SSL errors. If you are using the default <code class="literal">java.net</code>
|
|
client you don’t need the annotation (but it won’t do any harm). There is no support currently for other clients, but
|
|
it may be added in future releases.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_wiremock_and_spring_mvc_mocks" href="#_wiremock_and_spring_mvc_mocks"></a>87.5 WireMock and Spring MVC Mocks</h2></div></div></div><p>Spring Cloud Contract provides a convenience class that can load JSON WireMock stubs into a
|
|
Spring <code class="literal">MockRestServiceServer</code>. Here’s an example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest(webEnvironment = WebEnvironment.NONE)</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> WiremockForDocsMockServerApplicationTests {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> RestTemplate restTemplate;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> Service service;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> contextLoads() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// will read stubs classpath</span>
|
|
MockRestServiceServer server = WireMockRestServiceServer.with(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.restTemplate)
|
|
.baseUrl(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://example.org"</span>).stubs(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"classpath:/stubs/resource.json"</span>)
|
|
.build();
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// We're asserting if WireMock responded properly</span>
|
|
assertThat(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.service.go()).isEqualTo(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World"</span>);
|
|
server.verify();
|
|
}
|
|
}</pre><p>The <code class="literal">baseUrl</code> is prepended to all mock calls, and the <code class="literal">stubs()</code>
|
|
method takes a stub path resource pattern as an argument. So in this
|
|
example the stub defined at <code class="literal">/stubs/resource.json</code> is loaded into the
|
|
mock server, so if the <code class="literal">RestTemplate</code> is asked to visit
|
|
<code class="literal"><a class="link" href="http://example.org/" target="_top">http://example.org/</a></code> it will get the responses as declared
|
|
there. More than one stub pattern can be specified, and each one can
|
|
be a directory (for a recursive list of all ".json"), or a fixed
|
|
filename (like in the example above) or an ant-style pattern. The JSON
|
|
format is the normal WireMock format which you can read about in the
|
|
WireMock website.</p><p>Currently we support Tomcat, Jetty and Undertow as Spring Boot
|
|
embedded servers, and Wiremock itself has "native" support for a
|
|
particular version of Jetty (currently 9.2). To use the native Jetty
|
|
you need to add the native wiremock dependencies and exclude the
|
|
Spring Boot container if there is one.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_generating_stubs_using_restdocs" href="#_generating_stubs_using_restdocs"></a>87.6 Generating Stubs using RestDocs</h2></div></div></div><p><a class="link" href="https://projects.spring.io/spring-restdocs" target="_top">Spring RestDocs</a> can be
|
|
used to generate documentation (e.g. in asciidoctor format) for an
|
|
HTTP API with Spring MockMvc or Rest Assured. At the same time as you
|
|
generate documentation for your API, you can also generate WireMock
|
|
stubs, by using Spring Cloud Contract WireMock. Just write your normal
|
|
RestDocs test cases and use <code class="literal">@AutoConfigureRestDocs</code> to have stubs
|
|
automatically in the restdocs output directory. For example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureRestDocs(outputDir = "target/snippets")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureMockMvc</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ApplicationTests {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> MockMvc mockMvc;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> contextLoads() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
mockMvc.perform(get(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/resource"</span>))
|
|
.andExpect(content().string(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World"</span>))
|
|
.andDo(document(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"resource"</span>));
|
|
}
|
|
}</pre><p>From this test will be generated a WireMock stub at
|
|
"target/snippets/stubs/resource.json". It matches all GET requests to
|
|
the "/resource" path.</p><p>Without any additional configuration this will create a stub with a
|
|
request matcher for the HTTP method and all headers except "host" and
|
|
"content-length". To match the request more precisely, for example to
|
|
match the body of a POST or PUT, we need to explicitly create a
|
|
request matcher. This will do two things: 1) create a stub that only
|
|
matches the way you specify, 2) assert that the request in the test
|
|
case also matches the same conditions.</p><p>The main entry point for this is <code class="literal">WireMockRestDocs.verify()</code> which can
|
|
be used as a substitute for the <code class="literal">document()</code> convenience method. For
|
|
example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringRunner.class)</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@SpringBootTest</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureRestDocs(outputDir = "target/snippets")</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@AutoConfigureMockMvc</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> ApplicationTests {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Autowired</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">private</span> MockMvc mockMvc;
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> contextLoads() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
mockMvc.perform(post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/resource"</span>)
|
|
.content(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"id\":\"123456\",\"message\":\"Hello World\"}"</span>))
|
|
.andExpect(status().isOk())
|
|
.andDo(verify().jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.id"</span>)
|
|
.stub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"resource"</span>));
|
|
}
|
|
}</pre><p>So this contract is saying: any valid POST with an "id" field will get
|
|
back an the same response as in this test. You can chain together
|
|
calls to <code class="literal">.jsonPath()</code> to add additional matchers. The
|
|
<a class="link" href="https://github.com/jayway/JsonPath" target="_top">JayWay documentation</a> can help you
|
|
to get up to speed with JSON Path if it is unfamiliar to you.</p><p>Instead of the <code class="literal">jsonPath</code> and <code class="literal">contentType</code> convenience methods, you
|
|
can also use the WireMock APIs to verify the request matches the
|
|
created stub. Example:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@Test</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> contextLoads() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">throws</span> Exception {
|
|
mockMvc.perform(post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/resource"</span>)
|
|
.content(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"id\":\"123456\",\"message\":\"Hello World\"}"</span>))
|
|
.andExpect(status().isOk())
|
|
.andDo(verify()
|
|
.wiremock(WireMock.post(
|
|
urlPathEquals(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/resource"</span>))
|
|
.withRequestBody(matchingJsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.id"</span>))
|
|
.stub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"post-resource"</span>));
|
|
}</pre><p>The WireMock API is rich - you can match headers, query parameters,
|
|
and request body by regex as well as by json path - so this can useful
|
|
to create stubs with a wider range of parameters. The above example
|
|
will generate a stub something like this:</p><p><b>post-resource.json. </b>
|
|
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"request"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"url"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/resource"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"method"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"POST"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bodyPatterns"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">[</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"matchesJsonPath"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$.id"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}]</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">},</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"response"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"status"</span> : <span class="hl-number">200</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"body"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"headers"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"X-Application-Context"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application:-1"</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">,</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Content-Type"</span> : <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"text/plain"</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre><p>
|
|
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>You can use either the <code class="literal">wiremock()</code> method or the <code class="literal">jsonPath()</code>
|
|
and <code class="literal">contentType()</code> methods to create request matchers, but not both.</p></td></tr></table></div><p>On the consumer side, you can make the <code class="literal">resource.json</code> generated above
|
|
available on the classpath (by <a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html#_publishing_stubs_as_jars" target="_top">publishing stubs as JARs</a> for example).
|
|
After that, you can create a stub using WireMock in a
|
|
number of different ways, including as described above using
|
|
<code class="literal">@AutoConfigureWireMock(stubs="classpath:resource.json")</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_generating_contracts_using_restdocs" href="#_generating_contracts_using_restdocs"></a>87.7 Generating Contracts using RestDocs</h2></div></div></div><p>Another thing that can be generated with Spring RestDocs is the Spring Cloud
|
|
Contract DSL file and documentation. If you combine that with Spring Cloud
|
|
WireMock then you’re getting both the contracts and stubs.</p><p>Why would you want to use this feature? Some people in the community asked questions
|
|
about situation in which they would like to move to DSL based contract definition
|
|
but they already have a lot of Spring MVC tests. Using this feature allows you to generate
|
|
the contract files that you can later modify and move to proper folders so that the
|
|
plugin picks them up.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>You might wonder why this functionality is in the WireMock module.
|
|
Come to think of it, it does make sense since it makes little sense to generate
|
|
only contracts and not generate the stubs. That’s why we suggest to do both.</p></td></tr></table></div><p>Let’s imagine the following test:</p><pre class="programlisting"> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">this</span>.mockMvc.perform(post(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"/foo"</span>)
|
|
.accept(MediaType.APPLICATION_PDF)
|
|
.accept(MediaType.APPLICATION_JSON)
|
|
.contentType(MediaType.APPLICATION_JSON)
|
|
.content(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"{\"foo\": 23 }"</span>))
|
|
.andExpect(status().isOk())
|
|
.andExpect(content().string(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"bar"</span>))
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// first WireMock</span>
|
|
.andDo(WireMockRestDocs.verify()
|
|
.jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"$[?(@.foo >= 20)]"</span>)
|
|
.contentType(MediaType.valueOf(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"application/json"</span>))
|
|
.stub(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"shouldGrantABeerIfOldEnough"</span>))
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// then Contract DSL documentation</span>
|
|
.andDo(document(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"index"</span>, SpringCloudContractRestDocs.dslContract()));</pre><p>This will lead in the creation of the stub as presented in the previous
|
|
section, contract will get generated and a documentation file too.</p><p>The contract will be called <code class="literal">index.groovy</code> and look more like this.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.springframework.cloud.contract.spec.Contract
|
|
|
|
Contract.make {
|
|
request {
|
|
method <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'POST'</span>
|
|
url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/foo'</span>
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span> {<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"foo"</span>: <span class="hl-number">23</span> }
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">')
|
|
</span> headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Accept'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Type'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
}
|
|
}
|
|
response {
|
|
status <span class="hl-number">200</span>
|
|
body(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'
|
|
</span> bar
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">')
|
|
</span> headers {
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Type'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'application/json;charset=UTF-8'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
header(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'Content-Length'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'3'</span><span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">''</span>)
|
|
}
|
|
testMatchers {
|
|
jsonPath(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'$[?(@.foo >= 20)]'</span>, byType())
|
|
}
|
|
}
|
|
}</pre><p>the generated document (example for Asciidoc) will contain a formatted contract
|
|
(the location of this file would be <code class="literal">index/dsl-contract.adoc</code>).</p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_links" href="#_links"></a>88. Links</h2></div></div></div><p>Here you can find interesting links related to Spring Cloud Contract Verifier:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="https://github.com/spring-cloud/spring-cloud-contract/" target="_top">Spring Cloud Contract Github Repository</a></li><li class="listitem"><a class="link" href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/" target="_top">Spring Cloud Contract Samples</a></li><li class="listitem"><a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html" target="_top">Spring Cloud Contract Documentation</a></li><li class="listitem"><a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/deprecated" target="_top">Accurest Legacy Documentation</a></li><li class="listitem"><a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/#spring-cloud-contract-stub-runner" target="_top">Spring Cloud Contract Stub Runner Documentation</a></li><li class="listitem"><a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/#stub-runner-for-messaging" target="_top">Spring Cloud Contract Stub Runner Messaging Documentation</a></li><li class="listitem"><a class="link" href="https://gitter.im/spring-cloud/spring-cloud-contract" target="_top">Spring Cloud Contract Gitter</a></li><li class="listitem"><a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract-maven-plugin/" target="_top">Spring Cloud Contract Maven Plugin</a></li><li class="listitem"><a class="link" href="https://www.youtube.com/watch?v=sAAklvxmPmk" target="_top">Spring Cloud Contract WJUG Presentation by Marcin Grzejszczak</a></li></ul></div></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_vault" href="#_spring_cloud_vault"></a>Part XIII. Spring Cloud Vault</h1></div></div></div><div class="partintro"><div></div><p>© 2016-2017 The original authors.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p><span class="emphasis"><em>Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.</em></span></p></td></tr></table></div><p>Spring Cloud Vault Config provides client-side support for externalized configuration in a distributed system. With <a class="link" href="https://www.vaultproject.io" target="_top">HashiCorp’s Vault</a> you have a central place to manage external secret properties for applications across all environments. Vault can manage static and dynamic secrets such as username/password for remote applications/resources and provide credentials for external services such as MySQL, PostgreSQL, Apache Cassandra, MongoDB, Consul, AWS and more.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_quick_start_3" href="#_quick_start_3"></a>89. Quick Start</h2></div></div></div><p><span class="strong"><strong>Prerequisites</strong></span></p><p>To get started with Vault and this guide you need a
|
|
*NIX-like operating systems that provides:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">wget</code>, <code class="literal">openssl</code> and <code class="literal">unzip</code></li><li class="listitem">at least Java 7 and a properly configured <code class="literal">JAVA_HOME</code> environment variable</li></ul></div><p><span class="strong"><strong>Install Vault</strong></span></p><pre class="programlisting">$ src/<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>/bash/install_vault.sh</pre><p><span class="strong"><strong>Create SSL certificates for Vault</strong></span></p><pre class="programlisting">$ src/<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>/bash/create_certificates.sh</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p><code class="literal">create_certificates.sh</code> creates certificates in <code class="literal">work/ca</code> and a JKS truststore <code class="literal">work/keystore.jks</code>. If you want to run Spring Cloud Vault using this quickstart guide you need to configure the truststore the <code class="literal">spring.cloud.vault.ssl.trust-store</code> property to <code class="literal">file:work/keystore.jks</code>.</p></td></tr></table></div><p><a name="quickstart.vault.start" href="#quickstart.vault.start"></a><span class="strong"><strong>Start Vault server</strong></span></p><pre class="programlisting">$ src/<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>/bash/local_run_vault.sh</pre><p>Vault is started listening on <code class="literal">0.0.0.0:8200</code> using the <code class="literal">inmem</code> storage and
|
|
<code class="literal">https</code>.
|
|
Vault is sealed and not initialized when starting up.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you want to run tests, leave Vault uninitialized. The tests will
|
|
initialize Vault and create a root token <code class="literal">00000000-0000-0000-0000-000000000000</code>.</p></td></tr></table></div><p>If you want to use Vault for your application or give it a try then you need to initialize it first.</p><pre class="programlisting">$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">export</span> VAULT_ADDR=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"https://localhost:8200"</span>
|
|
$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">export</span> VAULT_SKIP_VERIFY=true <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># Don't do this for production</span>
|
|
$ vault init</pre><p>You should see something like:</p><pre class="programlisting">Key <span class="hl-number">1</span>: <span class="hl-number">7149</span>c6a2e16b8833f6eb1e76df03e47f6113a3288b3093faf5033d44f0e70fe701
|
|
Key <span class="hl-number">2</span>: <span class="hl-number">901</span>c534c7988c18c20435a85213c683bdcf0efcd82e38e2893779f152978c18c02
|
|
Key <span class="hl-number">3</span>: <span class="hl-number">03</span>ff3948575b1165a20c20ee7c3e6edf04f4cdbe0e82dbff5be49c63f98bc03a03
|
|
Key <span class="hl-number">4</span>: <span class="hl-number">216</span>ae5cc3ddaf93ceb8e1d15bb9fc3176653f5b738f5f3d1ee00cd7dccbe926e04
|
|
Key <span class="hl-number">5</span>: b2898fc8130929d569c1677ee69dc5f3be57d7c4b494a6062693ce0b1c4d93d805
|
|
Initial Root Token: <span class="hl-number">19</span>aefa97-cccc-bbbb-aaaa-<span class="hl-number">225940</span>e63d76
|
|
|
|
Vault initialized with <span class="hl-number">5</span> keys and a key threshold of <span class="hl-number">3.</span> Please
|
|
securely distribute the above keys. When the Vault is re-sealed,
|
|
restarted, or stopped, you must provide at least <span class="hl-number">3</span> of these keys
|
|
to unseal it again.
|
|
|
|
Vault does not store the master key. Without at least <span class="hl-number">3</span> keys,
|
|
your Vault will remain permanently sealed.</pre><p>Vault will initialize and return a set of unsealing keys and the root token.
|
|
Pick 3 keys and unseal Vault. Store the Vault token in the <code class="literal">VAULT_TOKEN</code>
|
|
environment variable.</p><pre class="programlisting">$ vault unseal (Key <span class="hl-number">1</span>)
|
|
$ vault unseal (Key <span class="hl-number">2</span>)
|
|
$ vault unseal (Key <span class="hl-number">3</span>)
|
|
$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">export</span> VAULT_TOKEN=(Root token)
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># Required to run Spring Cloud Vault tests after manual initialization</span>
|
|
$ vault token-create -id=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"00000000-0000-0000-0000-000000000000"</span> -policy=<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"root"</span></pre><p>Spring Cloud Vault accesses different resources. By default, the secret
|
|
backend is enabled which accesses secret config settings via JSON endpoints.</p><p>The HTTP service has resources in the form:</p><pre class="screen">/secret/{application}/{profile}
|
|
/secret/{application}
|
|
/secret/{defaultContext}/{profile}
|
|
/secret/{defaultContext}</pre><p>where the "application" is injected as the <code class="literal">spring.application.name</code> in the
|
|
<code class="literal">SpringApplication</code> (i.e. what is normally "application" in a regular
|
|
Spring Boot app), "profile" is an active profile (or comma-separated
|
|
list of properties). Properties retrieved from Vault will be used "as-is"
|
|
without further prefixing of the property names.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="_client_side_usage_2" href="#_client_side_usage_2"></a>90. Client Side Usage</h2></div></div></div><p>To use these features in an application, just build it as a Spring
|
|
Boot application that depends on <code class="literal">spring-cloud-vault-config</code> (e.g. see
|
|
the test cases). Example Maven configuration:</p><div class="example"><a name="d0e19675" href="#d0e19675"></a><p class="title"><b>Example 90.1. pom.xml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><parent></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.boot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-boot-starter-parent<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>1.5.4.RELEASE<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><relativePath /></span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- lookup parent from repository --></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></parent></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-starter-vault-config<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>Dalston.SR4<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.boot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-boot-starter-test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>test<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><build></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugins></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.boot<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-boot-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugins></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></build></span>
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!-- repositories also needed for snapshots and milestones --></span></pre></div></div><br class="example-break"><p>Then you can create a standard Spring Boot application, like this simple HTTP server:</p><div class="informalexample"><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@SpringBootApplication</span></em>
|
|
<em><span class="hl-annotation" style="color: gray">@RestController</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> Application {
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@RequestMapping("/")</span></em>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> String home() {
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">return</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"Hello World!"</span>;
|
|
}
|
|
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">static</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">void</span> main(String[] args) {
|
|
SpringApplication.run(Application.<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span>, args);
|
|
}
|
|
}</pre></div><p>When it runs it will pick up the external configuration from the
|
|
default local Vault server on port <code class="literal">8200</code> if it is running. To modify
|
|
the startup behavior you can change the location of the Vault server
|
|
using <code class="literal">bootstrap.properties</code> (like <code class="literal">application.properties</code> but for
|
|
the bootstrap phase of an application context), e.g.</p><div class="example"><a name="d0e19696" href="#d0e19696"></a><p class="title"><b>Example 90.2. bootstrap.yml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> host</span>: localhost
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> port</span>: <span class="hl-number">8200</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> scheme</span>: https
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> connection-timeout</span>: <span class="hl-number">5000</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> read-timeout</span>: <span class="hl-number">15000</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> order</span>: -<span class="hl-number">10</span></pre></div></div><br class="example-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">host</code> sets the hostname of the Vault host. The host name will be used
|
|
for SSL certificate validation</li><li class="listitem"><code class="literal">port</code> sets the Vault port</li><li class="listitem"><code class="literal">scheme</code> setting the scheme to <code class="literal">http</code> will use plain HTTP.
|
|
Supported schemes are <code class="literal">http</code> and <code class="literal">https</code>.</li><li class="listitem"><code class="literal">connection-timeout</code> sets the connection timeout in milliseconds</li><li class="listitem"><code class="literal">read-timeout</code> sets the read timeout in milliseconds</li><li class="listitem"><code class="literal">config.order</code> sets the order for the property source</li></ul></div><p>Enabling further integrations requires additional dependencies and
|
|
configuration. Depending on how you have set up Vault you might need
|
|
additional configuration like
|
|
<a class="link" href="http://cloud.spring.io/spring-cloud-vault/spring-cloud-vault.html#vault.config.ssl" target="_top">SSL</a> and
|
|
<a class="link" href="http://cloud.spring.io/spring-cloud-vault/spring-cloud-vault.html#vault.config.authentication" target="_top">authentication</a>.</p><p>If the application imports the <code class="literal">spring-boot-starter-actuator</code> project, the
|
|
status of the vault server will be available via the <code class="literal">/health</code> endpoint.</p><p>The vault health indicator can be enabled or disabled through the
|
|
property <code class="literal">health.vault.enabled</code> (default <code class="literal">true</code>).</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_authentication_2" href="#_authentication_2"></a>90.1 Authentication</h2></div></div></div><p>Vault requires an <a class="link" href="https://www.vaultproject.io/docs/concepts/auth.html" target="_top">authentication mechanism</a> to <a class="link" href="https://www.vaultproject.io/docs/concepts/tokens.html" target="_top">authorize client requests</a>.</p><p>Spring Cloud Vault supports multiple <a class="link" href="http://cloud.spring.io/spring-cloud-vault/spring-cloud-vault.html#vault.config.authentication" target="_top">authentication mechanisms</a> to authenticate applications with Vault.</p><p>For a quickstart, use the root token printed by the <a class="link" href="#quickstart.vault.start">Vault initialization</a>.</p><div class="example"><a name="d0e19786" href="#d0e19786"></a><p class="title"><b>Example 90.3. bootstrap.yml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> token</span>: <span class="hl-number">19</span>aefa97-cccc-bbbb-aaaa-<span class="hl-number">225940e63d</span>76</pre></div></div><br class="example-break"><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>Consider carefully your security requirements. Static token authentication is fine if you want quickly get started with Vault, but a static token is not protected any further. Any disclosure to unintended parties allows Vault use with the associated token roles.</p></td></tr></table></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="vault.config.authentication" href="#vault.config.authentication"></a>91. Authentication methods</h2></div></div></div><p>Different organizations have different requirements for security
|
|
and authentication. Vault reflects that need by shipping multiple authentication
|
|
methods. Spring Cloud Vault supports token and AppId authentication.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.authentication.token" href="#vault.config.authentication.token"></a>91.1 Token authentication</h2></div></div></div><p>Tokens are the core method for authentication within Vault.
|
|
Token authentication requires a static token to be provided using the
|
|
<a class="link" href="https://github.com/spring-cloud/spring-cloud-commons/blob/master/docs/src/main/asciidoc/spring-cloud-commons.adoc#the-bootstrap-application-context" target="_top">Bootstrap Application Context</a>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Token authentication is the default authentication method.
|
|
If a token is disclosed an unintended party gains access to Vault and
|
|
can access secrets for the intended client.</p></td></tr></table></div><div class="example"><a name="d0e19810" href="#d0e19810"></a><p class="title"><b>Example 91.1. bootstrap.yml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: TOKEN
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> token</span>: <span class="hl-number">00000000</span>-<span class="hl-number">0000</span>-<span class="hl-number">0000</span>-<span class="hl-number">0000</span>-<span class="hl-number">000000000000</span></pre></div></div><br class="example-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">authentication</code> setting this value to <code class="literal">TOKEN</code> selects the Token
|
|
authentication method</li><li class="listitem"><code class="literal">token</code> sets the static token to use</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/concepts/tokens.html" target="_top">Vault Documentation: Tokens</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.authentication.appid" href="#vault.config.authentication.appid"></a>91.2 AppId authentication</h2></div></div></div><p>Vault supports <a class="link" href="https://www.vaultproject.io/docs/auth/app-id.html" target="_top">AppId</a>
|
|
authentication that consists of two hard to guess tokens. The AppId
|
|
defaults to <code class="literal">spring.application.name</code> that is statically configured.
|
|
The second token is the UserId which is a part determined by the application,
|
|
usually related to the runtime environment. IP address, Mac address or a
|
|
Docker container name are good examples. Spring Cloud Vault Config supports
|
|
IP address, Mac address and static UserId’s (e.g. supplied via System properties).
|
|
The IP and Mac address are represented as Hex-encoded SHA256 hash.</p><p>IP address-based UserId’s use the local host’s IP address.</p><div class="example"><a name="d0e19846" href="#d0e19846"></a><p class="title"><b>Example 91.2. bootstrap.yml using SHA256 IP-Address UserId’s</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: APPID
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> app-id</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> user-id</span>: IP_ADDRESS</pre></div></div><br class="example-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">authentication</code> setting this value to <code class="literal">APPID</code> selects the AppId
|
|
authentication method</li><li class="listitem"><code class="literal">app-id-path</code> sets the path of the AppId mount to use</li><li class="listitem"><code class="literal">user-id</code> sets the UserId method. Possible values are <code class="literal">IP_ADDRESS</code>,
|
|
<code class="literal">MAC_ADDRESS</code> or a class name implementing a custom <code class="literal">AppIdUserIdMechanism</code></li></ul></div><p>The corresponding command to generate the IP address UserId from a command line is:</p><pre class="screen">$ echo -n 192.168.99.1 | sha256sum</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Including the line break of <code class="literal">echo</code> leads to a different hash value
|
|
so make sure to include the <code class="literal">-n</code> flag.</p></td></tr></table></div><p>Mac address-based UserId’s obtain their network device from the
|
|
localhost-bound device. The configuration also allows specifying
|
|
a <code class="literal">network-interface</code> hint to pick the right device. The value of
|
|
<code class="literal">network-interface</code> is optional and can be either an interface
|
|
name or interface index (0-based).</p><div class="example"><a name="d0e19899" href="#d0e19899"></a><p class="title"><b>Example 91.3. bootstrap.yml using SHA256 Mac-Address UserId’s</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: APPID
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> app-id</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> user-id</span>: MAC_ADDRESS
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> network-interface</span>: eth0</pre></div></div><br class="example-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">network-interface</code> sets network interface to obtain the physical address</li></ul></div><p>The corresponding command to generate the IP address UserId from a command line is:</p><pre class="screen">$ echo -n 0AFEDE1234AC | sha256sum</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The Mac address is specified uppercase and without colons.
|
|
Including the line break of <code class="literal">echo</code> leads to a different hash value
|
|
so make sure to include the <code class="literal">-n</code> flag.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_custom_userid" href="#_custom_userid"></a>91.2.1 Custom UserId</h3></div></div></div><p>The UserId generation is an open mechanism. You can set
|
|
<code class="literal">spring.cloud.vault.app-id.user-id</code> to any string and the configured
|
|
value will be used as static UserId.</p><p>A more advanced approach lets you set <code class="literal">spring.cloud.vault.app-id.user-id</code> to a
|
|
classname. This class must be on your classpath and must implement
|
|
the <code class="literal">org.springframework.cloud.vault.AppIdUserIdMechanism</code> interface
|
|
and the <code class="literal">createUserId</code> method. Spring Cloud Vault will obtain the UserId
|
|
by calling <code class="literal">createUserId</code> each time it authenticates using AppId to
|
|
obtain a token.</p><div class="example"><a name="d0e19945" href="#d0e19945"></a><p class="title"><b>Example 91.4. bootstrap.yml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: APPID
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> app-id</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> user-id</span>: com.examlple.MyUserIdMechanism</pre></div></div><br class="example-break"><div class="example"><a name="d0e19950" href="#d0e19950"></a><p class="title"><b>Example 91.5. MyUserIdMechanism.java</b></p><div class="example-contents"><pre class="programlisting">public class MyUserIdMechanism implements AppIdUserIdMechanism <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
|
|
<em><span class="hl-annotation" style="color: gray">@Override</span></em>
|
|
public String createUserId() <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">{</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> String userId </span>= ...
|
|
return userId;
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">}</span></pre></div></div><br class="example-break"><p>See also: <a class="link" href="https://www.vaultproject.io/docs/auth/app-id.html" target="_top">Vault Documentation: Using the App ID auth backend</a></p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_approle_authentication" href="#_approle_authentication"></a>91.3 AppRole authentication</h2></div></div></div><p><a class="link" href="https://www.vaultproject.io/docs/auth/app-id.html" target="_top">AppRole</a> is intended for machine
|
|
authentication, like the deprecated (since Vault 0.6.1) <a class="xref" href="#vault.config.authentication.appid" title="91.2 AppId authentication">Section 91.2, “AppId authentication”</a>.
|
|
AppRole authentication consists of two hard to guess (secret) tokens: RoleId and SecretId.</p><p>Spring Vault supports AppRole authentication by providing either RoleId only
|
|
or together with a provided SecretId (push or pull mode).</p><p>RoleId and optionally SecretId must be provided by configuration,
|
|
Spring Vault will not look up these or create a custom SecretId.</p><div class="example"><a name="d0e19972" href="#d0e19972"></a><p class="title"><b>Example 91.6. bootstrap.yml with AppRole authentication properties</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: APPROLE
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> app-role</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role-id</span>: bde2076b-cccb-<span class="hl-number">3</span>cf0-d57e-bca7b1e83a52</pre></div></div><br class="example-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">role-id</code> sets the RoleId.</li></ul></div><div class="example"><a name="d0e19983" href="#d0e19983"></a><p class="title"><b>Example 91.7. bootstrap.yml with all AppRole authentication properties</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: APPROLE
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> app-role</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role-id</span>: bde2076b-cccb-<span class="hl-number">3</span>cf0-d57e-bca7b1e83a52
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> secret-id</span>: <span class="hl-number">1696536f</span>-<span class="hl-number">1976</span>-<span class="hl-number">73</span>b1-b241-<span class="hl-number">0</span>b4213908d39
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> app-auth-path</span>: approle</pre></div></div><br class="example-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">role-id</code> sets the RoleId.</li><li class="listitem"><code class="literal">secret-id</code> sets the SecretId. SecretId can be omitted if AppRole is configured without requiring SecretId (See <code class="literal">bind_secret_id</code>)</li><li class="listitem"><code class="literal">approle-path</code> sets the path of the approle authentication mount to use</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/auth/approle.html" target="_top">Vault Documentation: Using the AppRole auth backend</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.authentication.awsec2" href="#vault.config.authentication.awsec2"></a>91.4 AWS-EC2 authentication</h2></div></div></div><p>The <a class="link" href="https://www.vaultproject.io/docs/auth/aws-ec2.html" target="_top">aws-ec2</a>
|
|
auth backend provides a secure introduction mechanism
|
|
for AWS EC2 instances, allowing automated retrieval of a Vault
|
|
token. Unlike most Vault authentication backends, this backend
|
|
does not require first-deploying, or provisioning security-sensitive
|
|
credentials (tokens, username/password, client certificates, etc.).
|
|
Instead, it treats AWS as a Trusted Third Party and uses the
|
|
cryptographically signed dynamic metadata information that uniquely
|
|
represents each EC2 instance.</p><div class="example"><a name="d0e20019" href="#d0e20019"></a><p class="title"><b>Example 91.8. bootstrap.yml using AWS-EC2 Authentication</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: AWS_EC2</pre></div></div><br class="example-break"><p>AWS-EC2 authentication enables nonce by default to follow
|
|
the Trust On First Use (TOFU) principle. Any unintended party that
|
|
gains access to the PKCS#7 identity metadata can authenticate
|
|
against Vault.</p><p>During the first login, Spring Cloud Vault generates a nonce
|
|
that is stored in the auth backend aside the instance Id.
|
|
Re-authentication requires the same nonce to be sent. Any other
|
|
party does not have the nonce and can raise an alert in Vault for
|
|
further investigation.</p><p>The nonce is kept in memory and is lost during application restart.</p><p>AWS-EC2 authentication roles are optional and default to the AMI.
|
|
You can configure the authentication role by setting the
|
|
<code class="literal">spring.cloud.vault.aws-ec2.role</code> property.</p><div class="example"><a name="d0e20035" href="#d0e20035"></a><p class="title"><b>Example 91.9. bootstrap.yml with configured role</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: AWS_EC2
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> aws-ec2</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: application-server</pre></div></div><br class="example-break"><div class="example"><a name="d0e20040" href="#d0e20040"></a><p class="title"><b>Example 91.10. bootstrap.yml with all AWS EC2 authentication properties</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: AWS_EC2
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> aws-ec2</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: application-server
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> aws-ec2-path</span>: aws-ec2
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> identity-document</span>: http://...</pre></div></div><br class="example-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">authentication</code> setting this value to <code class="literal">AWS_EC2</code> selects the AWS EC2
|
|
authentication method</li><li class="listitem"><code class="literal">role</code> sets the role name of the AWS EC2 role definition</li><li class="listitem"><code class="literal">aws-ec2-path</code> sets the path of the AWS EC2 mount to use</li><li class="listitem"><code class="literal">identity-document</code> sets URL of the PKCS#7 AWS EC2 identity document</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/auth/aws-ec2.html" target="_top">Vault Documentation: Using the aws-ec2 auth backend</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.authentication.clientcert" href="#vault.config.authentication.clientcert"></a>91.5 TLS certificate authentication</h2></div></div></div><p>The <code class="literal">cert</code> auth backend allows authentication using SSL/TLS client
|
|
certificates that are either signed by a CA or self-signed.</p><p>To enable <code class="literal">cert</code> authentication you need to:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">Use SSL, see <a class="xref" href="#vault.config.ssl" title="95. Vault Client SSL configuration">Chapter 95, <i>Vault Client SSL configuration</i></a></li><li class="listitem">Configure a Java <code class="literal">Keystore</code> that contains the client
|
|
certificate and the private key</li><li class="listitem">Set the <code class="literal">spring.cloud.vault.authentication</code> to <code class="literal">CERT</code></li></ol></div><div class="example"><a name="d0e20105" href="#d0e20105"></a><p class="title"><b>Example 91.11. bootstrap.yml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: CERT
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ssl</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> key-store</span>: classpath:keystore.jks
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> key-store-password</span>: changeit
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cert-auth-path</span>: cert</pre></div></div><br class="example-break"><p>See also: <a class="link" href="https://www.vaultproject.io/docs/auth/cert.html" target="_top">Vault Documentation: Using the Cert auth backend</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.authentication.cubbyhole" href="#vault.config.authentication.cubbyhole"></a>91.6 Cubbyhole authentication</h2></div></div></div><p>Cubbyhole authentication uses Vault primitives to provide a secured authentication
|
|
workflow. Cubbyhole authentication uses tokens as primary login method.
|
|
An ephemeral token is used to obtain a second, login VaultToken from Vault’s
|
|
Cubbyhole secret backend. The login token is usually longer-lived and used to
|
|
interact with Vault. The login token will be retrieved from a wrapped
|
|
response stored at <code class="literal">/cubbyhole/response</code>.</p><p><span class="strong"><strong>Creating a wrapped token</strong></span></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Response Wrapping for token creation requires Vault 0.6.0 or higher.</p></td></tr></table></div><div class="example"><a name="d0e20128" href="#d0e20128"></a><p class="title"><b>Example 91.12. Crating and storing tokens</b></p><div class="example-contents"><pre class="programlisting">$ vault token-create -wrap-ttl="10m"
|
|
Key Value
|
|
--- -----
|
|
wrapping_token: 397ccb93-ff6c-b17b-9389-380b01ca2645
|
|
wrapping_token_ttl: 0h10m0s
|
|
wrapping_token_creation_time: 2016-09-18 20:29:48.652957077 +0200 CEST
|
|
wrapped_accessor: 46b6aebb-187f-932a-26d7-4f3d86a68319</pre></div></div><br class="example-break"><div class="example"><a name="d0e20133" href="#d0e20133"></a><p class="title"><b>Example 91.13. bootstrap.yml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> authentication</span>: CUBBYHOLE
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> token</span>: <span class="hl-number">397</span>ccb93-ff6c-b17b-<span class="hl-number">9389</span>-<span class="hl-number">380</span>b01ca2645</pre></div></div><br class="example-break"><p>See also:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="https://www.vaultproject.io/docs/concepts/tokens.html" target="_top">Vault Documentation: Tokens</a></li><li class="listitem"><a class="link" href="https://www.vaultproject.io/docs/secrets/cubbyhole/index.html" target="_top">Vault Documentation: Cubbyhole Secret Backend</a></li><li class="listitem"><a class="link" href="https://www.vaultproject.io/docs/concepts/response-wrapping.html" target="_top">Vault Documentation: Response Wrapping</a></li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="vault.config.backends" href="#vault.config.backends"></a>92. Secret Backends</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.generic" href="#vault.config.backends.generic"></a>92.1 Generic Backend</h2></div></div></div><p>Spring Cloud Vault supports at the basic level the generic secret
|
|
backend. The generic secret backend allows storage of arbitrary
|
|
values as key-value store. A single context can store one or many
|
|
key-value tuples. Contexts can be organized hierarchically.
|
|
Spring Cloud Vault allows using the Application name
|
|
and a default context name (<code class="literal">application</code>) in combination with active
|
|
profiles.</p><pre class="screen">/secret/{application}/{profile}
|
|
/secret/{application}
|
|
/secret/{default-context}/{profile}
|
|
/secret/{default-context}</pre><p>The application name is determined by the properties:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">spring.cloud.vault.generic.application-name</code></li><li class="listitem"><code class="literal">spring.cloud.vault.application-name</code></li><li class="listitem"><code class="literal">spring.application.name</code></li></ul></div><p>Secrets can be obtained from other folders within the generic backend by adding their
|
|
paths to the application name, separated by commas. For example, given the application
|
|
name <code class="literal">usefulapp,mysql1,projectx/aws</code>, each of these folders will be used:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">/secret/usefulapp</code></li><li class="listitem"><code class="literal">/secret/mysql1</code></li><li class="listitem"><code class="literal">/secret/projectx/aws</code></li></ul></div><p>Spring Cloud Vault adds all active profiles to the list of possible context paths.
|
|
No active profiles will skip accessing contexts with a profile name.</p><p>Properties are exposed like they are stored (i.e. without additional prefixes).</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> generic</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: secret
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> profile-separator</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'/'</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> default-context</span>: application
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> application-name</span>: my-app</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">false</code> disables the secret backend
|
|
config usage</li><li class="listitem"><code class="literal">backend</code> sets the path of the secret mount to use</li><li class="listitem"><code class="literal">default-context</code> sets the context name used by all applications</li><li class="listitem"><code class="literal">application-name</code> overrides the application name for use in the generic backend</li><li class="listitem"><code class="literal">profile-separator</code> separates the profile name from the context in
|
|
property sources with profiles</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/generic/index.html" target="_top">Vault Documentation: Using the generic secret backend</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.consul" href="#vault.config.backends.consul"></a>92.2 Consul</h2></div></div></div><p>Spring Cloud Vault can obtain credentials for HashiCorp Consul.
|
|
The Consul integration requires the <code class="literal">spring-cloud-vault-config-consul</code>
|
|
dependency.</p><div class="example"><a name="d0e20247" href="#d0e20247"></a><p class="title"><b>Example 92.1. pom.xml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-vault-config-consul<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>Dalston.SR4<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span></pre></div></div><br class="example-break"><p>The integration can be enabled by setting
|
|
<code class="literal">spring.cloud.vault.consul.enabled=true</code> (default <code class="literal">false</code>) and
|
|
providing the role name with <code class="literal">spring.cloud.vault.consul.role=…</code>.</p><p>The obtained token is stored in <code class="literal">spring.cloud.consul.token</code>
|
|
so using Spring Cloud Consul can pick up the generated
|
|
credentials without further configuration. You can configure
|
|
the property name by setting <code class="literal">spring.cloud.vault.consul.token-property</code>.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> consul</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: readonly
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: consul
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> token-property</span>: spring.cloud.consul.token</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">true</code> enables the Consul backend config usage</li><li class="listitem"><code class="literal">role</code> sets the role name of the Consul role definition</li><li class="listitem"><code class="literal">backend</code> sets the path of the Consul mount to use</li><li class="listitem"><code class="literal">token-property</code> sets the property name in which the Consul ACL token is stored</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/consul/index.html" target="_top">Vault Documentation: Setting up Consul with Vault</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.rabbitmq" href="#vault.config.backends.rabbitmq"></a>92.3 RabbitMQ</h2></div></div></div><p>Spring Cloud Vault can obtain credentials for RabbitMQ.</p><p>The RabbitMQ integration requires the <code class="literal">spring-cloud-vault-config-rabbitmq</code>
|
|
dependency.</p><div class="example"><a name="d0e20312" href="#d0e20312"></a><p class="title"><b>Example 92.2. pom.xml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-vault-config-rabbitmq<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>Dalston.SR4<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span></pre></div></div><br class="example-break"><p>The integration can be enabled by setting
|
|
<code class="literal">spring.cloud.vault.rabbitmq.enabled=true</code> (default <code class="literal">false</code>)
|
|
and providing the role name with <code class="literal">spring.cloud.vault.rabbitmq.role=…</code>.</p><p>Username and password are stored in <code class="literal">spring.rabbitmq.username</code>
|
|
and <code class="literal">spring.rabbitmq.password</code> so using Spring Boot will pick up the generated
|
|
credentials without further configuration. You can configure the property names
|
|
by setting <code class="literal">spring.cloud.vault.rabbitmq.username-property</code> and
|
|
<code class="literal">spring.cloud.vault.rabbitmq.password-property</code>.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> rabbitmq</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: readonly
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: rabbitmq
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username-property</span>: spring.rabbitmq.username
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password-property</span>: spring.rabbitmq.password</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">true</code> enables the RabbitMQ backend config usage</li><li class="listitem"><code class="literal">role</code> sets the role name of the RabbitMQ role definition</li><li class="listitem"><code class="literal">backend</code> sets the path of the RabbitMQ mount to use</li><li class="listitem"><code class="literal">username-property</code> sets the property name in which the RabbitMQ username is stored</li><li class="listitem"><code class="literal">password-property</code> sets the property name in which the RabbitMQ password is stored</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/rabbitmq/index.html" target="_top">Vault Documentation: Setting up RabbitMQ with Vault</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.aws" href="#vault.config.backends.aws"></a>92.4 AWS</h2></div></div></div><p>Spring Cloud Vault can obtain credentials for AWS.</p><p>The AWS integration requires the <code class="literal">spring-cloud-vault-config-aws</code>
|
|
dependency.</p><div class="example"><a name="d0e20388" href="#d0e20388"></a><p class="title"><b>Example 92.3. pom.xml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-vault-config-aws<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>Dalston.SR4<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span></pre></div></div><br class="example-break"><p>The integration can be enabled by setting
|
|
<code class="literal">spring.cloud.vault.aws=true</code> (default <code class="literal">false</code>)
|
|
and providing the role name with <code class="literal">spring.cloud.vault.aws.role=…</code>.</p><p>The access key and secret key are stored in <code class="literal">cloud.aws.credentials.accessKey</code>
|
|
and <code class="literal">cloud.aws.credentials.secretKey</code> so using Spring Cloud AWS will pick up the generated
|
|
credentials without further configuration. You can configure the property names
|
|
by setting <code class="literal">spring.cloud.vault.aws.access-key-property</code> and
|
|
<code class="literal">spring.cloud.vault.aws.secret-key-property</code>.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> aws</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: readonly
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: aws
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> access-key-property</span>: cloud.aws.credentials.accessKey
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> secret-key-property</span>: cloud.aws.credentials.secretKey</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">true</code> enables the AWS backend config usage</li><li class="listitem"><code class="literal">role</code> sets the role name of the AWS role definition</li><li class="listitem"><code class="literal">backend</code> sets the path of the AWS mount to use</li><li class="listitem"><code class="literal">access-key-property</code> sets the property name in which the AWS access key is stored</li><li class="listitem"><code class="literal">secret-key-property</code> sets the property name in which the AWS secret key is stored</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/aws/index.html" target="_top">Vault Documentation: Setting up AWS with Vault</a></p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="vault.config.backends.database-backends" href="#vault.config.backends.database-backends"></a>93. Database backends</h2></div></div></div><p>Vault supports several database secret backends to generate database
|
|
credentials dynamically based on configured roles. This means
|
|
services that need to access a database no longer need to configure
|
|
credentials: they can request them from Vault, and use Vault’s leasing
|
|
mechanism to more easily roll keys.</p><p>Spring Cloud Vault integrates with these backends:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="xref" href="#vault.config.backends.cassandra" title="93.1 Apache Cassandra">Section 93.1, “Apache Cassandra”</a></li><li class="listitem"><a class="xref" href="#vault.config.backends.mongodb" title="93.2 MongoDB">Section 93.2, “MongoDB”</a></li><li class="listitem"><a class="xref" href="#vault.config.backends.mysql" title="93.3 MySQL">Section 93.3, “MySQL”</a></li><li class="listitem"><a class="xref" href="#vault.config.backends.postgresql" title="93.4 PostgreSQL">Section 93.4, “PostgreSQL”</a></li></ul></div><p>Using a database secret backend requires to enable the
|
|
backend in the configuration and the <code class="literal">spring-cloud-vault-config-databases</code>
|
|
dependency.</p><div class="example"><a name="d0e20479" href="#d0e20479"></a><p class="title"><b>Example 93.1. pom.xml</b></p><div class="example-contents"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-vault-config-databases<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>Dalston.SR4<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span></pre></div></div><br class="example-break"><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Enabling multiple JDBC-compliant databases will generate credentials
|
|
and store them by default in the same property keys hence property names for
|
|
JDBC secrets need to be configured separately.</p></td></tr></table></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.cassandra" href="#vault.config.backends.cassandra"></a>93.1 Apache Cassandra</h2></div></div></div><p>Spring Cloud Vault can obtain credentials for Apache Cassandra.
|
|
The integration can be enabled by setting
|
|
<code class="literal">spring.cloud.vault.cassandra.enabled=true</code> (default <code class="literal">false</code>) and
|
|
providing the role name with <code class="literal">spring.cloud.vault.cassandra.role=…</code>.</p><p>Username and password are stored in <code class="literal">spring.data.cassandra.username</code>
|
|
and <code class="literal">spring.data.cassandra.password</code> so using Spring Boot will pick
|
|
up the generated credentials without further configuration.
|
|
You can configure the property names by setting
|
|
<code class="literal">spring.cloud.vault.cassandra.username-property</code> and
|
|
<code class="literal">spring.cloud.vault.cassandra.password-property</code>.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cassandra</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: readonly
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: cassandra
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username-property</span>: spring.data.cassandra.username
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password-property</span>: spring.data.cassandra.username</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">true</code> enables the Cassandra backend config usage</li><li class="listitem"><code class="literal">role</code> sets the role name of the Cassandra role definition</li><li class="listitem"><code class="literal">backend</code> sets the path of the Cassandra mount to use</li><li class="listitem"><code class="literal">username-property</code> sets the property name in which the Cassandra username is stored</li><li class="listitem"><code class="literal">password-property</code> sets the property name in which the Cassandra password is stored</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/cassandra/index.html" target="_top">Vault Documentation: Setting up Apache Cassandra with Vault</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.mongodb" href="#vault.config.backends.mongodb"></a>93.2 MongoDB</h2></div></div></div><p>Spring Cloud Vault can obtain credentials for MongoDB.
|
|
The integration can be enabled by setting
|
|
<code class="literal">spring.cloud.vault.mongodb.enabled=true</code> (default <code class="literal">false</code>) and
|
|
providing the role name with <code class="literal">spring.cloud.vault.mongodb.role=…</code>.</p><p>Username and password are stored in <code class="literal">spring.data.mongodb.username</code>
|
|
and <code class="literal">spring.data.mongodb.password</code> so using Spring Boot will
|
|
pick up the generated credentials without further configuration.
|
|
You can configure the property names by setting
|
|
<code class="literal">spring.cloud.vault.mongodb.username-property</code> and
|
|
<code class="literal">spring.cloud.vault.mongodb.password-property</code>.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> mongodb</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: readonly
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: mongodb
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username-property</span>: spring.data.mongodb.username
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password-property</span>: spring.data.mongodb.password</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">true</code> enables the MongodB backend config usage</li><li class="listitem"><code class="literal">role</code> sets the role name of the MongoDB role definition</li><li class="listitem"><code class="literal">backend</code> sets the path of the MongoDB mount to use</li><li class="listitem"><code class="literal">username-property</code> sets the property name in which the MongoDB username is stored</li><li class="listitem"><code class="literal">password-property</code> sets the property name in which the MongoDB password is stored</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/mongodb/index.html" target="_top">Vault Documentation: Setting up MongoDB with Vault</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.mysql" href="#vault.config.backends.mysql"></a>93.3 MySQL</h2></div></div></div><p>Spring Cloud Vault can obtain credentials for MySQL.
|
|
The integration can be enabled by setting
|
|
<code class="literal">spring.cloud.vault.mysql.enabled=true</code> (default <code class="literal">false</code>) and
|
|
providing the role name with <code class="literal">spring.cloud.vault.mysql.role=…</code>.</p><p>Username and password are stored in <code class="literal">spring.datasource.username</code>
|
|
and <code class="literal">spring.datasource.password</code> so using Spring Boot will
|
|
pick up the generated credentials without further configuration.
|
|
You can configure the property names by setting
|
|
<code class="literal">spring.cloud.vault.mysql.username-property</code> and
|
|
<code class="literal">spring.cloud.vault.mysql.password-property</code>.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> mysql</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: readonly
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: mysql
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username-property</span>: spring.datasource.username
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password-property</span>: spring.datasource.username</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">true</code> enables the MySQL backend config usage</li><li class="listitem"><code class="literal">role</code> sets the role name of the MySQL role definition</li><li class="listitem"><code class="literal">backend</code> sets the path of the MySQL mount to use</li><li class="listitem"><code class="literal">username-property</code> sets the property name in which the MySQL username is stored</li><li class="listitem"><code class="literal">password-property</code> sets the property name in which the MySQL password is stored</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/mysql/index.html" target="_top">Vault Documentation: Setting up MySQL with Vault</a></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="vault.config.backends.postgresql" href="#vault.config.backends.postgresql"></a>93.4 PostgreSQL</h2></div></div></div><p>Spring Cloud Vault can obtain credentials for PostgreSQL.
|
|
The integration can be enabled by setting
|
|
<code class="literal">spring.cloud.vault.postgresql.enabled=true</code> (default <code class="literal">false</code>) and
|
|
providing the role name with <code class="literal">spring.cloud.vault.postgresql.role=…</code>.</p><p>Username and password are stored in <code class="literal">spring.datasource.username</code>
|
|
and <code class="literal">spring.datasource.password</code> so using Spring Boot will
|
|
pick up the generated credentials without further configuration.
|
|
You can configure the property names by setting
|
|
<code class="literal">spring.cloud.vault.postgresql.username-property</code> and
|
|
<code class="literal">spring.cloud.vault.postgresql.password-property</code>.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> postgresql</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span>
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> role</span>: readonly
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> backend</span>: postgresql
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> username-property</span>: spring.datasource.username
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> password-property</span>: spring.datasource.username</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">enabled</code> setting this value to <code class="literal">true</code> enables the PostgreSQL backend config usage</li><li class="listitem"><code class="literal">role</code> sets the role name of the PostgreSQL role definition</li><li class="listitem"><code class="literal">backend</code> sets the path of the PostgreSQL mount to use</li><li class="listitem"><code class="literal">username-property</code> sets the property name in which the PostgreSQL username is stored</li><li class="listitem"><code class="literal">password-property</code> sets the property name in which the PostgreSQL password is stored</li></ul></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/secrets/postgresql/index.html" target="_top">Vault Documentation: Setting up PostgreSQL with Vault</a></p></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="vault.config.fail-fast" href="#vault.config.fail-fast"></a>94. Vault Client Fail Fast</h2></div></div></div><p>In some cases, it may be desirable to fail startup of a service if
|
|
it cannot connect to the Vault Server. If this is the desired
|
|
behavior, set the bootstrap configuration property
|
|
<code class="literal">spring.cloud.vault.fail-fast=true</code> and the client will halt with
|
|
an Exception.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> fail-fast</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre></div></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="vault.config.ssl" href="#vault.config.ssl"></a>95. Vault Client SSL configuration</h2></div></div></div><p>SSL can be configured declaratively by setting various properties.
|
|
You can set either <code class="literal">javax.net.ssl.trustStore</code> to configure
|
|
JVM-wide SSL settings or <code class="literal">spring.cloud.vault.ssl.trust-store</code>
|
|
to set SSL settings only for Spring Cloud Vault Config.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> ssl</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> trust-store</span>: classpath:keystore.jks
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> trust-store-password</span>: changeit</pre></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">trust-store</code> sets the resource for the trust-store. SSL-secured Vault
|
|
communication will validate the Vault SSL certificate with the specified
|
|
trust-store.</li><li class="listitem"><code class="literal">trust-store-password</code> sets the trust-store password</li></ul></div><p>Please note that configuring <code class="literal">spring.cloud.vault.ssl.*</code> can be only
|
|
applied when either Apache Http Components or the OkHttp client
|
|
is on your class-path.</p></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="vault-lease-renewal" href="#vault-lease-renewal"></a>96. Lease lifecycle management (renewal and revocation)</h2></div></div></div><p>With every secret, Vault creates a lease:
|
|
metadata containing information such as a time duration,
|
|
renewability, and more.</p><p>Vault promises that the data will be valid for the given duration,
|
|
or Time To Live (TTL). Once the lease is expired, Vault can
|
|
revoke the data, and the consumer of the secret can no longer
|
|
be certain that it is valid.</p><p>Spring Cloud Vault maintains a lease lifecycle beyond
|
|
the creation of login tokens and secrets. That said,
|
|
login tokens and secrets associated with a lease
|
|
are scheduled for renewal just before the lease expires
|
|
until terminal expiry.
|
|
Application shutdown revokes obtained login tokens and renewable
|
|
leases.</p><p>Secret service and database backends (such as MongoDB or MySQL)
|
|
usually generate a renewable lease so generated credentials will
|
|
be disabled on application shutdown.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>Static tokens are not renewed or revoked.</p></td></tr></table></div><p>Lease renewal and revocation is enabled by default and can
|
|
be disabled by setting <code class="literal">spring.cloud.vault.config.lifecycle.enabled</code>
|
|
to <code class="literal">false</code>. This is not recommended as leases can expire and
|
|
Spring Cloud Vault cannot longer access Vault or services
|
|
using generated credentials and valid credentials remain active
|
|
after application shutdown.</p><div class="informalexample"><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring.cloud.vault</span>:
|
|
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> config.lifecycle.enabled</span>: <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">true</span></pre></div><p>See also: <a class="link" href="https://www.vaultproject.io/docs/concepts/lease.html" target="_top">Vault Documentation: Lease, Renew, and Revoke</a></p></div></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="_appendix_compendium_of_configuration_properties" href="#_appendix_compendium_of_configuration_properties"></a>Part XIV. Appendix: Compendium of Configuration Properties</h1></div></div></div><div class="partintro"><div></div><div class="informaltable"><table style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; border-left: 0.5pt solid ; border-right: 0.5pt solid ; "><colgroup><col class="col_1"><col class="col_2"><col class="col_3"></colgroup><thead><tr><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Name</th><th style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top">Default</th><th style="border-bottom: 0.5pt solid ; " align="left" valign="top">Description</th></tr></thead><tbody><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.fail-on-error</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to say that a process should fail if there is an encryption or decryption
|
|
error.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>A symmetric key. As a stronger alternative consider using a keystore.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.key-store.alias</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Alias for a key in the store.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.key-store.location</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Location of the key store file, e.g. classpath:/keystore.jks.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.key-store.password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Password that locks the keystore.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.key-store.secret</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Secret protecting the key (defaults to the same as the password).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.rsa.algorithm</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The RSA algorithm to use (DEFAULT or OEAP). Once it is set do not change it (or
|
|
existing ciphers will not a decryptable).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.rsa.salt</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>deadbeef</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Salt for the random secret used to encrypt cipher text. Once it is set do not
|
|
change it (or existing ciphers will not a decryptable).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>encrypt.rsa.strong</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that "strong" AES encryption should be used internally. If
|
|
true then the GCM algorithm is applied to the AES encrypted bytes. Default is
|
|
false (in which case "standard" CBC is used instead). Once it is set do not
|
|
change it (or existing ciphers will not a decryptable).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.bus.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.bus.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.bus.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.consul.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.consul.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.consul.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.env.post.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable changing the Environment through a POST to /env.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.features.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.features.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.features.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.pause.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable the /pause endpoint (to send Lifecycle.stop()).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.pause.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.pause.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.refresh.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable the /refresh endpoint to refresh configuration and re-initialize refresh scoped beans.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.refresh.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.refresh.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable the /restart endpoint to restart the application context.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.pause-endpoint.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.pause-endpoint.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.pause-endpoint.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.resume-endpoint.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.resume-endpoint.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.resume-endpoint.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.restart.timeout</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.resume.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable the /resume endpoint (to send Lifecycle.start()).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.resume.id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.resume.sensitive</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>endpoints.zookeeper.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable the /zookeeper endpoint to inspect the state of zookeeper.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.allow-redirects</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether server can redirect a client request to a backup server/cluster.
|
|
If set to false, the server will handle the request directly, If set to true, it
|
|
may send HTTP redirect to the client, with a new server location.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.availability-zones</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the list of availability zones (used in AWS data centers) for the region in
|
|
which this instance resides.
|
|
</p><p> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSeconds.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.backup-registry-impl</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the name of the implementation which implements BackupRegistry to fetch the
|
|
registry information as a fall back option for only the first time when the eureka
|
|
client starts.
|
|
</p><p> This may be needed for applications which needs additional resiliency for registry
|
|
information without which it cannot operate.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.cache-refresh-executor-exponential-back-off-bound</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Cache refresh executor exponential back off related property. It is a maximum
|
|
multiplier value for retry delay, in case where a sequence of timeouts occurred.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.cache-refresh-executor-thread-pool-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The thread pool size for the cacheRefreshExecutor to initialise with</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.client-data-accept</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>EurekaAccept name for client data accept</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.decoder-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>This is a transient config and once the latest codecs are stable, can be removed
|
|
(as there will only be one)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.disable-delta</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether the eureka client should disable fetching of delta and should
|
|
rather resort to getting the full registry information.
|
|
</p><p> Note that the delta fetches can reduce the traffic tremendously, because the rate
|
|
of change with the eureka server is normally much lower than the rate of fetches.
|
|
</p><p> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSeconds</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.dollar-replacement</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>_-</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get a replacement string for Dollar sign <code>$</code> during
|
|
serializing/deserializing information in eureka server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that the Eureka client is enabled.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.encoder-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>This is a transient config and once the latest codecs are stable, can be removed
|
|
(as there will only be one)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.escape-char-replacement</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>__</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get a replacement string for underscore sign <code>_</code> during
|
|
serializing/deserializing information in eureka server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-connection-idle-timeout-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how much time (in seconds) that the HTTP connections to eureka server can
|
|
stay idle before it can be closed.
|
|
</p><p> In the AWS environment, it is recommended that the values is 30 seconds or less,
|
|
since the firewall cleans up the connection information after a few mins leaving
|
|
the connection hanging in limbo</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-server-connect-timeout-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>5</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how long to wait (in seconds) before a connection to eureka server needs
|
|
to timeout. Note that the connections in the client are pooled by
|
|
org.apache.http.client.HttpClient and this setting affects the actual connection
|
|
creation and also the wait time to get the connection from the pool.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-server-d-n-s-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the DNS name to be queried to get the list of eureka servers.This information
|
|
is not required if the contract returns the service urls by implementing
|
|
serviceUrls.
|
|
</p><p> The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the
|
|
eureka client expects the DNS to configured a certain way so that it can fetch
|
|
changing eureka servers dynamically.
|
|
</p><p> The changes are effective at runtime.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-server-port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the port to be used to construct the service url to contact eureka server when
|
|
the list of eureka servers come from the DNS.This information is not required if
|
|
the contract returns the service urls eurekaServerServiceUrls(String).
|
|
</p><p> The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the
|
|
eureka client expects the DNS to configured a certain way so that it can fetch
|
|
changing eureka servers dynamically.
|
|
</p><p> The changes are effective at runtime.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-server-read-timeout-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>8</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how long to wait (in seconds) before a read from eureka server needs to
|
|
timeout.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-server-total-connections</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>200</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the total number of connections that is allowed from eureka client to all
|
|
eureka servers.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-server-total-connections-per-host</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>50</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the total number of connections that is allowed from eureka client to a eureka
|
|
server host.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-server-u-r-l-context</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the URL context to be used to construct the service url to contact eureka
|
|
server when the list of eureka servers come from the DNS. This information is not
|
|
required if the contract returns the service urls from eurekaServerServiceUrls.
|
|
</p><p> The DNS mechanism is used when useDnsForFetchingServiceUrls is set to true and the
|
|
eureka client expects the DNS to configured a certain way so that it can fetch
|
|
changing eureka servers dynamically. The changes are effective at runtime.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.eureka-service-url-poll-interval-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how often(in seconds) to poll for changes to eureka server information.
|
|
Eureka servers could be added or removed and this setting controls how soon the
|
|
eureka clients should know about it.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.fetch-registry</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether this client should fetch eureka registry information from eureka
|
|
server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.fetch-remote-regions-registry</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Comma separated list of regions for which the eureka registry information will be
|
|
fetched. It is mandatory to define the availability zones for each of these regions
|
|
as returned by availabilityZones. Failing to do so, will result in failure of
|
|
discovery client startup.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.filter-only-up-instances</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether to get the applications after filtering the applications for
|
|
instances with only InstanceStatus UP states.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.g-zip-content</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether the content fetched from eureka server has to be compressed
|
|
whenever it is supported by the server. The registry information from the eureka
|
|
server is compressed for optimum network traffic.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.heartbeat-executor-exponential-back-off-bound</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Heartbeat executor exponential back off related property. It is a maximum
|
|
multiplier value for retry delay, in case where a sequence of timeouts occurred.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.heartbeat-executor-thread-pool-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The thread pool size for the heartbeatExecutor to initialise with</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.initial-instance-info-replication-interval-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>40</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how long initially (in seconds) to replicate instance info to the eureka
|
|
server</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.instance-info-replication-interval-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how often(in seconds) to replicate instance changes to be replicated to
|
|
the eureka server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.log-delta-diff</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether to log differences between the eureka server and the eureka
|
|
client in terms of registry information.
|
|
</p><p> Eureka client tries to retrieve only delta changes from eureka server to minimize
|
|
network traffic. After receiving the deltas, eureka client reconciles the
|
|
information from the server to verify it has not missed out some information.
|
|
Reconciliation failures could happen when the client has had network issues
|
|
communicating to server.If the reconciliation fails, eureka client gets the full
|
|
registry information.
|
|
</p><p> While getting the full registry information, the eureka client can log the
|
|
differences between the client and the server and this setting controls that.
|
|
</p><p> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSecondsr</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.on-demand-update-status-change</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>If set to true, local status updates via ApplicationInfoManager will trigger
|
|
on-demand (but rate limited) register/updates to remote eureka servers</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.prefer-same-zone-eureka</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether or not this instance should try to use the eureka server in the
|
|
same zone for latency and/or other reason.
|
|
</p><p> Ideally eureka clients are configured to talk to servers in the same zone
|
|
</p><p> The changes are effective at runtime at the next registry fetch cycle as specified
|
|
by registryFetchIntervalSeconds</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.property-resolver</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.proxy-host</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the proxy host to eureka server if any.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.proxy-password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the proxy password if any.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.proxy-port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the proxy port to eureka server if any.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.proxy-user-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the proxy user name if any.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.region</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>us-east-1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the region (used in AWS datacenters) where this instance resides.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.register-with-eureka</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether or not this instance should register its information with eureka
|
|
server for discovery by others.
|
|
</p><p> In some cases, you do not want your instances to be discovered whereas you just
|
|
want do discover other instances.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.registry-fetch-interval-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how often(in seconds) to fetch the registry information from the eureka
|
|
server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.registry-refresh-single-vip-address</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether the client is only interested in the registry information for a
|
|
single VIP.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.service-url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Map of availability zone to list of fully qualified URLs to communicate with eureka
|
|
server. Each value can be a single URL or a comma separated list of alternative
|
|
locations.
|
|
</p><p> Typically the eureka server URLs carry protocol,host,port,context and version
|
|
information if any. Example:
|
|
<a class="link" href="http://ec2-256-156-243-129.compute-1.amazonaws.com:7001/eureka/" target="_top">http://ec2-256-156-243-129.compute-1.amazonaws.com:7001/eureka/</a>
|
|
</p><p> The changes are effective at runtime at the next service url refresh cycle as
|
|
specified by eurekaServiceUrlPollIntervalSeconds.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.transport</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.client.use-dns-for-fetching-service-urls</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether the eureka client should use the DNS mechanism to fetch a list of
|
|
eureka servers to talk to. When the DNS name is updated to have additional servers,
|
|
that information is used immediately after the eureka client polls for that
|
|
information as specified in eurekaServiceUrlPollIntervalSeconds.
|
|
</p><p> Alternatively, the service urls can be returned serviceUrls, but the users should
|
|
implement their own mechanism to return the updated list in case of changes.
|
|
</p><p> The changes are effective at runtime.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.dashboard.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to enable the Eureka dashboard. Default true.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.dashboard.path</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>/</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The path to the Eureka dashboard (relative to the servlet path). Defaults to "/".</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.a-s-g-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the AWS autoscaling group name associated with this instance. This information
|
|
is specifically used in an AWS environment to automatically put an instance out of
|
|
service after the instance is launched and it has been disabled for traffic..</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.app-group-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get the name of the application group to be registered with eureka.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.appname</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>unknown</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get the name of the application to be registered with eureka.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.data-center-info</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Returns the data center this instance is deployed. This information is used to get
|
|
some AWS specific instance information if the instance is deployed in AWS.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.default-address-resolution-order</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>[]</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.environment</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.health-check-url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the absolute health check page URL for this instance. The users can provide
|
|
the healthCheckUrlPath if the health check page resides in the same instance
|
|
talking to eureka, else in the cases where the instance is a proxy for some other
|
|
server, users can provide the full URL. If the full URL is provided it takes
|
|
precedence.
|
|
</p><p> <p>
|
|
It is normally used for making educated decisions based on the health of the
|
|
instance - for example, it can be used to determine whether to proceed deployments
|
|
to an entire farm or stop the deployments without causing further damage. The full
|
|
URL should follow the format <a class="link" href="http://${eureka.hostname}:7001/" target="_top">http://${eureka.hostname}:7001/</a> where the value
|
|
${eureka.hostname} is replaced at runtime.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.health-check-url-path</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>/health</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the relative health check URL path for this instance. The health check page
|
|
URL is then constructed out of the hostname and the type of communication - secure
|
|
or unsecure as specified in securePort and nonSecurePort.
|
|
</p><p> It is normally used for making educated decisions based on the health of the
|
|
instance - for example, it can be used to determine whether to proceed deployments
|
|
to an entire farm or stop the deployments without causing further damage.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.home-page-url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the absolute home page URL for this instance. The users can provide the
|
|
homePageUrlPath if the home page resides in the same instance talking to eureka,
|
|
else in the cases where the instance is a proxy for some other server, users can
|
|
provide the full URL. If the full URL is provided it takes precedence.
|
|
</p><p> It is normally used for informational purposes for other services to use it as a
|
|
landing page. The full URL should follow the format <a class="link" href="http://${eureka.hostname}:7001/" target="_top">http://${eureka.hostname}:7001/</a>
|
|
where the value ${eureka.hostname} is replaced at runtime.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.home-page-url-path</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>/</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the relative home page URL Path for this instance. The home page URL is then
|
|
constructed out of the hostName and the type of communication - secure or unsecure.
|
|
</p><p> It is normally used for informational purposes for other services to use it as a
|
|
landing page.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.host-info</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.hostname</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The hostname if it can be determined at configuration time (otherwise it will be
|
|
guessed from OS primitives).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.inet-utils</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.initial-status</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Initial status to register with rmeote Eureka server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.instance-enabled-onit</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether the instance should be enabled for taking traffic as soon as it
|
|
is registered with eureka. Sometimes the application might need to do some
|
|
pre-processing before it is ready to take traffic.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.instance-id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get the unique Id (within the scope of the appName) of this instance to be
|
|
registered with eureka.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.ip-address</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get the IPAdress of the instance. This information is for academic purposes only as
|
|
the communication from other instances primarily happen using the information
|
|
supplied in {@link #getHostName(boolean)}.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.lease-expiration-duration-in-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>90</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates the time in seconds that the eureka server waits since it received the
|
|
last heartbeat before it can remove this instance from its view and there by
|
|
disallowing traffic to this instance.
|
|
</p><p> Setting this value too long could mean that the traffic could be routed to the
|
|
instance even though the instance is not alive. Setting this value too small could
|
|
mean, the instance may be taken out of traffic because of temporary network
|
|
glitches.This value to be set to atleast higher than the value specified in
|
|
leaseRenewalIntervalInSeconds.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.lease-renewal-interval-in-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates how often (in seconds) the eureka client needs to send heartbeats to
|
|
eureka server to indicate that it is still alive. If the heartbeats are not
|
|
received for the period specified in leaseExpirationDurationInSeconds, eureka
|
|
server will remove the instance from its view, there by disallowing traffic to this
|
|
instance.
|
|
</p><p> Note that the instance could still not take traffic if it implements
|
|
HealthCheckCallback and then decides to make itself unavailable.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.metadata-map</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the metadata name/value pairs associated with this instance. This information
|
|
is sent to eureka server and can be used by other instances.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.namespace</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get the namespace used to find properties. Ignored in Spring Cloud.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.non-secure-port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>80</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get the non-secure port on which the instance should receive traffic.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.non-secure-port-enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether the non-secure port should be enabled for traffic or not.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.prefer-ip-address</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to say that, when guessing a hostname, the IP address of the server should be
|
|
used in prference to the hostname reported by the OS.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.registry.default-open-for-traffic-count</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Value used in determining when leases are cancelled, default to 1 for standalone.
|
|
Should be set to 0 for peer replicated eurekas</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.registry.expected-number-of-renews-per-min</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.secure-health-check-url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the absolute secure health check page URL for this instance. The users can
|
|
provide the secureHealthCheckUrl if the health check page resides in the same
|
|
instance talking to eureka, else in the cases where the instance is a proxy for
|
|
some other server, users can provide the full URL. If the full URL is provided it
|
|
takes precedence.
|
|
</p><p> <p>
|
|
It is normally used for making educated decisions based on the health of the
|
|
instance - for example, it can be used to determine whether to proceed deployments
|
|
to an entire farm or stop the deployments without causing further damage. The full
|
|
URL should follow the format <a class="link" href="http://${eureka.hostname}:7001/" target="_top">http://${eureka.hostname}:7001/</a> where the value
|
|
${eureka.hostname} is replaced at runtime.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.secure-port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>443</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Get the Secure port on which the instance should receive traffic.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.secure-port-enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Indicates whether the secure port should be enabled for traffic or not.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.secure-virtual-host-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>unknown</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the secure virtual host name defined for this instance.
|
|
</p><p> This is typically the way other instance would find this instance by using the
|
|
secure virtual host name.Think of this as similar to the fully qualified domain
|
|
name, that the users of your services will need to find this instance.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.status-page-url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the absolute status page URL path for this instance. The users can provide the
|
|
statusPageUrlPath if the status page resides in the same instance talking to
|
|
eureka, else in the cases where the instance is a proxy for some other server,
|
|
users can provide the full URL. If the full URL is provided it takes precedence.
|
|
</p><p> It is normally used for informational purposes for other services to find about the
|
|
status of this instance. Users can provide a simple HTML indicating what is the
|
|
current status of the instance.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.status-page-url-path</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>/info</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the relative status page URL path for this instance. The status page URL is
|
|
then constructed out of the hostName and the type of communication - secure or
|
|
unsecure as specified in securePort and nonSecurePort.
|
|
</p><p> It is normally used for informational purposes for other services to find about the
|
|
status of this instance. Users can provide a simple HTML indicating what is the
|
|
current status of the instance.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.instance.virtual-host-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>unknown</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the virtual host name defined for this instance.
|
|
</p><p> This is typically the way other instance would find this instance by using the
|
|
virtual host name.Think of this as similar to the fully qualified domain name, that
|
|
the users of your services will need to find this instance.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.a-s-g-cache-expiry-timeout-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.a-s-g-query-timeout-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>300</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.a-s-g-update-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.a-w-s-access-id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.a-w-s-secret-key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.batch-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.binding-strategy</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.delta-retention-timer-interval-in-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.disable-delta</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.disable-delta-for-remote-regions</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.disable-transparent-fallback-to-other-region</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.e-i-p-bind-rebind-retries</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>3</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.e-i-p-binding-retry-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.e-i-p-binding-retry-interval-ms-when-unbound</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.enable-replicated-request-compression</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.enable-self-preservation</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.eviction-interval-timer-in-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.g-zip-content-from-remote-region</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.json-codec-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.list-auto-scaling-groups-role-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>ListAutoScalingGroups</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.log-identity-headers</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.max-elements-in-peer-replication-pool</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.max-elements-in-status-replication-pool</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.max-idle-thread-age-in-minutes-for-peer-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>15</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.max-idle-thread-in-minutes-age-for-status-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.max-threads-for-peer-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>20</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.max-threads-for-status-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.max-time-for-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.min-threads-for-peer-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>5</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.min-threads-for-status-replication</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.number-of-replication-retries</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>5</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.peer-eureka-nodes-update-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.peer-eureka-status-refresh-time-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.peer-node-connect-timeout-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>200</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.peer-node-connection-idle-timeout-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.peer-node-read-timeout-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>200</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.peer-node-total-connections</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.peer-node-total-connections-per-host</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>500</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.prime-aws-replica-connections</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.property-resolver</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.rate-limiter-burst-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.rate-limiter-enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.rate-limiter-full-fetch-average-rate</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>100</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.rate-limiter-privileged-clients</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.rate-limiter-registry-fetch-average-rate</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>500</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.rate-limiter-throttle-standard-clients</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.registry-sync-retries</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.registry-sync-retry-wait-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-app-whitelist</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-connect-timeout-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-connection-idle-timeout-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-fetch-thread-pool-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>20</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-read-timeout-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-registry-fetch-interval</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-total-connections</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-total-connections-per-host</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>500</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-trust-store</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-trust-store-password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>changeit</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-urls</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.remote-region-urls-with-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.renewal-percent-threshold</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0.85</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.renewal-threshold-update-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.response-cache-auto-expiration-in-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>180</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.response-cache-update-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.retention-time-in-m-s-in-delta-queue</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.route53-bind-rebind-retries</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>3</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.route53-binding-retry-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.route53-domain-t-t-l</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.sync-when-timestamp-differs</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.use-read-only-response-cache</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.wait-time-in-ms-when-sync-empty</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>eureka.server.xml-codec-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>feign.compression.request.mime-types</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>[text/xml, application/xml, application/json]</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The list of supported mime types.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>feign.compression.request.min-request-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2048</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The minimum threshold content size.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>health.config.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that the config server health indicator should be installed.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>health.config.time-to-live</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Time to live for cached result, in milliseconds. Default 300000 (5 min).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>hystrix.metrics.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable Hystrix metrics polling. Defaults to true.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>hystrix.metrics.polling-interval-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Interval between subsequent polling of metrics. Defaults to 2000 ms.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>management.health.refresh.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable the health endpoint for the refresh scope.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>management.health.zookeeper.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable the health endpoint for zookeeper.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>netflix.atlas.batch-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>netflix.atlas.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>netflix.atlas.uri</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>netflix.metrics.servo.cache-warning-threshold</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>When the <code class="literal">ServoMonitorCache</code> reaches this size, a warning is logged.
|
|
This will be useful if you are using string concatenation in RestTemplate urls.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>netflix.metrics.servo.registry-class</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>com.netflix.servo.BasicMonitorRegistry</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Fully qualified class name for monitor registry used by Servo.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>proxy.auth.load-balanced</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>proxy.auth.routes</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Authentication strategy per route.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.bus.ack.destination-service</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Service that wants to listen to acks. By default null (meaning all services).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.bus.ack.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to switch off acks (default on).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.bus.destination</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>springCloudBus</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Name of Spring Cloud Stream destination for messages.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.bus.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that the bus is enabled.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.bus.env.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to switch off environment change events (default on).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.bus.refresh.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to switch off refresh events (default on).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.bus.trace.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to switch on tracing of acks (default off).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.cloudfoundry.discovery.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that discovery is enabled.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.cloudfoundry.discovery.heartbeat-frequency</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>5000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Frequency in milliseconds of poll for heart beat. The client will poll on this
|
|
frequency and broadcast a list of service ids.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.cloudfoundry.discovery.org</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Organization name to authenticate with (default to user’s default).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.cloudfoundry.discovery.password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Password for user to authenticate and obtain token.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.cloudfoundry.discovery.space</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Space name to authenticate with (default to user’s default).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.cloudfoundry.discovery.url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><a class="link" href="https://api.run.pivotal.io" target="_top">https://api.run.pivotal.io</a></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>URL of Cloud Foundry API (Cloud Controller).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.cloudfoundry.discovery.username</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Username to authenticate (usually an email address).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.allow-override</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that {@link #isSystemPropertiesOverride()
|
|
systemPropertiesOverride} can be used. Set to false to prevent users from changing
|
|
the default accidentally. Default true.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.authorization</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Authorization token used by the client to connect to the server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.discovery.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that config server discovery is enabled (config server URL will be
|
|
looked up via discovery).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.discovery.service-id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>configserver</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Service id to locate config server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to say that remote configuration is enabled. Default true;</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.fail-fast</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that failure to connect to the server is fatal (default false).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.label</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The label name to use to pull remote configuration properties. The default is set
|
|
on the server (generally "master" for a git based server).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Name of application used to fetch remote properties.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.override-none</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that when {@link #setAllowOverride(boolean) allowOverride} is
|
|
true, external properties should take lowest priority, and not override any
|
|
existing property sources (including local config files). Default false.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.override-system-properties</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that the external properties should override system properties.
|
|
Default true.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The password to use (HTTP Basic) when contacting the remote server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.profile</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>default</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The default profile to use when fetching remote configuration (comma-separated).
|
|
Default is "default".</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.retry.initial-interval</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Initial retry interval in milliseconds.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.retry.max-attempts</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>6</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Maximum number of attempts.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.retry.max-interval</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Maximum interval for backoff.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.retry.multiplier</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1.1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Multiplier for next interval.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.bootstrap</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag indicating that the config server should initialize its own Environment with
|
|
properties from the remote repository. Off by default because it delays startup but
|
|
can be useful when embedding the server in another application.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.default-application-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Default application name when incoming requests do not have a specific one.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.default-label</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Default repository label when incoming requests do not have a specific label.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.default-profile</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>default</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Default application profile when incoming requests do not have a specific one.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.encrypt.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable decryption of environment properties before sending to client.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.basedir</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Base directory for local working copy of repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.clone-on-start</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that the repository should be cloned on startup (not on demand).
|
|
Generally leads to slower startup but faster first query.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.default-label</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.environment</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.force-pull</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that the repository should force pull. If true discard any local
|
|
changes and take from remote repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.git-factory</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Password for authentication with remote repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.repos</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Map of repository identifier to location and other properties.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.search-paths</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Search paths to use within local working copy. By default searches only the root.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.timeout</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Timeout (in seconds) for obtaining HTTP or SSH connection (if applicable). Default
|
|
5 seconds.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.uri</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>URI of remote repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.git.username</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Username for authentication with remote repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.health.repositories</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.native.fail-on-error</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to determine how to handle exceptions during decryption (default false).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.native.search-locations</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>[]</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Locations to search for configuration files. Defaults to the same as a Spring Boot
|
|
app so [classpath:/,classpath:/config/,file:./,file:./config/].</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.native.version</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Version string to be reported for native repository</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.overrides</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Extra map for a property source to be sent to all clients unconditionally.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Prefix for configuration resource paths (default is empty). Useful when embedding
|
|
in another application when you don’t want to change the context path or servlet
|
|
path.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.strip-document-from-yaml</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to indicate that YAML documents that are text or collections (not a map)
|
|
should be returned in "native" form.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.svn.basedir</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Base directory for local working copy of repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.svn.default-label</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>trunk</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The default label for environment properties requests.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.svn.environment</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.svn.password</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Password for authentication with remote repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.svn.search-paths</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Search paths to use within local working copy. By default searches only the root.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.svn.uri</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>URI of remote repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.server.svn.username</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Username for authentication with remote repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.token</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Security Token passed thru to underlying environment repository.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.uri</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p><a class="link" href="http://localhost:8888" target="_top">http://localhost:8888</a></p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The URI of the remote server (default <a class="link" href="http://localhost:8888" target="_top">http://localhost:8888</a>).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.config.username</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The username to use (HTTP Basic) when contacting the remote server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.acl-token</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.data-key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>data</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>If format is Format.PROPERTIES or Format.YAML
|
|
then the following field is used as key to look up consul for configuration.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.default-context</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>application</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.fail-fast</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Throw exceptions during config lookup if true, otherwise, log warnings.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.format</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>config</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.profile-separator</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>,</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.watch.delay</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The value of the fixed delay for the watch in millis. Defaults to 1000.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.watch.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>If the watch is enabled. Defaults to true.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.config.watch.wait-time</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>55</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The number of seconds to wait (or block) for watch query, defaults to 55.
|
|
Needs to be less than default ConsulClient (defaults to 60). To increase ConsulClient
|
|
timeout create a ConsulClient bean with a custom ConsulRawClient with a custom
|
|
HttpClient.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.acl-token</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.catalog-services-watch-delay</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.catalog-services-watch-timeout</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.default-query-tag</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Tag to query for in service list if one is not listed in serverListQueryTags.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.default-zone-metadata-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zone</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Service instance zone comes from metadata.
|
|
This allows changing the metadata tag name.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Is service discovery enabled?</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.fail-fast</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Throw exceptions during service registration if true, otherwise, log
|
|
warnings (defaults to true).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.health-check-interval</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10s</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>How often to perform the health check (e.g. 10s)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.health-check-path</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>/health</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Alternate server path to invoke for health checking</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.health-check-timeout</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Timeout for health check (e.g. 10s)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.health-check-url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Custom health check url to override default</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.heartbeat.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.heartbeat.heartbeat-interval</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.heartbeat.interval-ratio</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.heartbeat.ttl-unit</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>s</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.heartbeat.ttl-value</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>30</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.host-info</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.hostname</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Hostname to use when accessing server</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.instance-id</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Unique service instance id</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.instance-zone</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Service instance zone</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.ip-address</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>IP address to use when accessing service (must also set preferIpAddress
|
|
to use)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.lifecycle.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.management-port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Port to register the management service under (defaults to management port)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.management-suffix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>management</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Suffix to use when registering management service</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.management-tags</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Tags to use when registering management service</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Port to register the service under (defaults to listening port)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.prefer-agent-address</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Source of how we will determine the address to use</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.prefer-ip-address</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Use ip address rather than hostname during registration</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.query-passing</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Add the 'passing` parameter to /v1/health/service/serviceName.
|
|
This pushes health check passing to the server.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.register</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Register as a service in consul.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.register-health-check</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Register health check in consul. Useful during development of a service.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.scheme</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Whether to register an http or https service</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.server-list-query-tags</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Map of serviceId’s → tag to query for in server list.
|
|
This allows filtering services by a single tag.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.service-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Service name</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.discovery.tags</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Tags to use when registering service</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Is spring cloud consul enabled</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.host</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>localhost</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Consul agent hostname. Defaults to 'localhost'.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>8500</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Consul agent port. Defaults to '8500'.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.retry.initial-interval</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Initial retry interval in milliseconds.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.retry.max-attempts</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>6</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Maximum number of attempts.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.retry.max-interval</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>2000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Maximum interval for backoff.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.consul.retry.multiplier</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1.1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Multiplier for next interval.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.hypermedia.refresh.fixed-delay</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>5000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.hypermedia.refresh.initial-delay</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.inetutils.default-hostname</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>localhost</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The default hostname. Used in case of errors.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.inetutils.default-ip-address</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>127.0.0.1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The default ipaddress. Used in case of errors.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.inetutils.ignored-interfaces</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>List of Java regex expressions for network interfaces that will be ignored.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.inetutils.preferred-networks</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>List of Java regex expressions for network addresses that will be ignored.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.inetutils.timeout-seconds</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Timeout in seconds for calculating hostname.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.inetutils.use-only-site-local-interfaces</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Use only interfaces with site local addresses. See {@link InetAddress#isSiteLocalAddress()} for more details.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.loadbalancer.retry.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.binders</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.bindings</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.consul.binder.event-timeout</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>5</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.consumer-defaults</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.default-binder</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.dynamic-destinations</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>[]</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.ignore-unknown-properties</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.instance-count</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.instance-index</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.producer-defaults</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.rabbit.binder.admin-adresses</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>[]</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.rabbit.binder.compression-level</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.rabbit.binder.nodes</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>[]</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.stream.rabbit.bindings</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.base-sleep-time-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>50</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Initial amount of time to wait between retries</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.block-until-connected-unit</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The unit of time related to blocking on connection to Zookeeper</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.block-until-connected-wait</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Wait time to block on connection to Zookeeper</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.connect-string</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>localhost:2181</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Connection string to the Zookeeper cluster</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.default-health-endpoint</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Default health endpoint that will be checked to verify that a dependency is alive</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.dependencies</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Mapping of alias to ZookeeperDependency. From Ribbon perspective the alias
|
|
is actually serviceID since Ribbon can’t accept nested structures in serviceID</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.dependency-configurations</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.dependency-names</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.discovery.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.discovery.instance-host</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Predefined host with which a service can register itself in Zookeeper. Corresponds
|
|
to the {code address} from the URI spec.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.discovery.instance-port</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Port to register the service under (defaults to listening port)</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.discovery.metadata</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Gets the metadata name/value pairs associated with this instance. This information
|
|
is sent to zookeeper and can be used by other instances.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.discovery.register</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Register as a service in zookeeper.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.discovery.root</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>/services</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Root Zookeeper folder in which all instances are registered</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.discovery.uri-spec</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>{scheme}://{address}:{port}</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The URI specification to resolve during service registration in Zookeeper</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Is Zookeeper enabled</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.max-retries</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>10</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Max number of times to retry</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.max-sleep-ms</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>500</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Max time in ms to sleep on each retry</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.cloud.zookeeper.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Common prefix that will be applied to all Zookeeper dependencies' paths</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.integration.poller.fixed-delay</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1000</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Fixed delay for default poller.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.integration.poller.max-messages-per-poll</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Maximum messages per poll for the default poller.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.integration.enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Enable Spring Integration sleuth instrumentation.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.integration.patterns</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>*</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>An array of simple patterns against which channel names will be matched. Default is * (all channels). See org.springframework.util.PatternMatchUtils.simpleMatch(String, String).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.async.class-name-key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>class</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Simple name of the class with a method annotated with {@code @Async}
|
|
from which the asynchronous process started
|
|
</p><p> @see org.springframework.scheduling.annotation.Async</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.async.method-name-key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>method</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Name of the method annotated with {@code @Async}
|
|
</p><p> @see org.springframework.scheduling.annotation.Async</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.async.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Prefix for header names if they are added as tags.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.async.thread-name-key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>thread</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Name of the thread that executed the async method
|
|
</p><p> @see org.springframework.scheduling.annotation.Async</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.headers</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Additional headers that should be added as tags if they exist. If the header
|
|
value is multi-valued, the tag value will be a comma-separated, single-quoted
|
|
list.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.host</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.host</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The domain portion of the URL or host header. Example:
|
|
"mybucket.s3.amazonaws.com". Used to filter by host as opposed to ip address.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.method</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.method</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The HTTP method, or verb, such as "GET" or "POST". Used to filter against an
|
|
http route.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.path</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.path</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The absolute http path, without any query parameters. Example:
|
|
"/objects/abcd-ff". Used to filter against an http route, portably with zipkin
|
|
v1. In zipkin v1, only equals filters are supported. Dropping query parameters
|
|
makes the number of distinct URIs less. For example, one can query for the same
|
|
resource, regardless of signing parameters encoded in the query line. This does
|
|
not reduce cardinality to a HTTP single route. For example, it is common to
|
|
express a route as an http URI template like "/resource/{resource_id}". In
|
|
systems where only equals queries are available, searching for
|
|
{@code http.uri=/resource} won’t match if the actual request was
|
|
"/resource/abcd-ff". Historical note: This was commonly expressed as "http.uri"
|
|
in zipkin, eventhough it was most often just a path.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Prefix for header names if they are added as tags.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.request-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.request.size</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The size of the non-empty HTTP request body, in bytes. Ex. "16384"
|
|
</p><p> <p>Large uploads can exceed limits or contribute directly to latency.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.response-size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.response.size</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The size of the non-empty HTTP response body, in bytes. Ex. "16384"
|
|
</p><p> <p>Large downloads can exceed limits or contribute directly to latency.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.status-code</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.status_code</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The HTTP response code, when not in 2xx range. Ex. "503" Used to filter for
|
|
error status. 2xx range are not logged as success codes are less interesting
|
|
for latency troubleshooting. Omitting saves at least 20 bytes per span.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.http.url</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>http.url</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The entire URL, including the scheme, host and query parameters if available.
|
|
Ex.
|
|
"https://mybucket.s3.amazonaws.com/objects/abcd-ff?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Algorithm=AWS4-HMAC-SHA256…​"
|
|
Combined with {@link #method}, you can understand the fully-qualified
|
|
request line. This is optional as it may include private data or be of
|
|
considerable length.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.hystrix.command-group</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>commandGroup</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Name of the command group. Hystrix uses the command group key to group
|
|
together commands such as for reporting, alerting, dashboards,
|
|
or team/library ownership.
|
|
</p><p> @see com.netflix.hystrix.HystrixCommandGroupKey</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.hystrix.command-key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>commandKey</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Name of the command key. Describes the name for the given command.
|
|
A key to represent a {@link com.netflix.hystrix.HystrixCommand} for
|
|
monitoring, circuit-breakers, metrics publishing, caching and other such uses.
|
|
</p><p> @see com.netflix.hystrix.HystrixCommandKey</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.hystrix.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Prefix for header names if they are added as tags.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.hystrix.thread-pool-key</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>threadPoolKey</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Name of the thread pool key. The thread-pool key represents a {@link com.netflix.hystrix.HystrixThreadPool}
|
|
for monitoring, metrics publishing, caching, and other such uses. A {@link com.netflix.hystrix.HystrixCommand}
|
|
is associated with a single {@link com.netflix.hystrix.HystrixThreadPool} as
|
|
retrieved by the {@link com.netflix.hystrix.HystrixThreadPoolKey} injected into it,
|
|
or it defaults to one created using the {@link com.netflix.hystrix.HystrixCommandGroupKey}
|
|
it is created with.
|
|
</p><p> @see com.netflix.hystrix.HystrixThreadPoolKey</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.message.headers</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Additional headers that should be added as tags if they exist. If the header
|
|
value is not a String it will be converted to a String using its toString()
|
|
method.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.message.payload.size</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>message/payload-size</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>An estimate of the size of the payload if available.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.message.payload.type</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>message/payload-type</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The type of the payload.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.message.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>message/</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Prefix for header names if they are added as tags.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.mvc.controller-class</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>mvc.controller.class</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The lower case, hyphen delimited name of the class that processes the request.
|
|
Ex. class named "BookController" will result in "book-controller" tag value.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.keys.mvc.controller-method</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>mvc.controller.method</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The lower case, hyphen delimited name of the class that processes the request.
|
|
Ex. method named "listOfBooks" will result in "list-of-books" tag value.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.metric.span.accepted-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>counter.span.accepted</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.metric.span.dropped-name</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>counter.span.dropped</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.sampler.percentage</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>0.1</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Percentage of requests that should be sampled. E.g. 1.0 - 100% requests should be
|
|
sampled. The precision is whole-numbers only (i.e. there’s no support for 0.1% of
|
|
the traces).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>spring.sleuth.trace-id128</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>When true, generate 128-bit trace IDs instead of 64-bit ones.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.add-host-header</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>false</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to determine whether the proxy forwards the Host header.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.add-proxy-headers</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to determine whether the proxy adds X-Forwarded-* headers.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.host.max-per-route-connections</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>20</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The maximum number of connections that can be used by a single route.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.host.max-total-connections</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>200</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The maximum number of total connections the proxy can hold open to backends.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.ignore-local-service</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.ignore-security-headers</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to say that SECURITY_HEADERS are added to ignored headers if spring security is on the classpath.
|
|
By setting ignoreSecurityHeaders to false we can switch off this default behaviour. This should be used together with
|
|
disabling the default spring security headers
|
|
see <a class="link" href="https://docs.spring.io/spring-security/site/docs/current/reference/html/headers.html#default-security-headers" target="_top">https://docs.spring.io/spring-security/site/docs/current/reference/html/headers.html#default-security-headers</a></p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.ignored-headers</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Names of HTTP headers to ignore completely (i.e. leave them out of downstream
|
|
requests and drop them from downstream responses).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.ignored-patterns</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.ignored-services</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Set of service names not to consider for proxying automatically. By default all
|
|
services in the discovery client will be proxied.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>A common prefix for all routes.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.remove-semicolon-content</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to say that path elements past the first semicolon can be dropped.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.retryable</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag for whether retry is supported by default (assuming the routes themselves
|
|
support it).</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.ribbon-isolation-strategy</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"> </td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.routes</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Map of route names to properties.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.s-e-c-u-r-i-t-y-h-e-a-d-e-r-s</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Headers that are generally expected to be added by Spring Security, and hence often
|
|
duplicated if the proxy and the backend are secured with Spring. By default they
|
|
are added to the ignored headers if Spring Security is present and ignoreSecurityHeaders = true.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.semaphore.max-semaphores</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>100</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>The maximum number of total semaphores for Hystrix.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.sensitive-headers</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"> </td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>List of sensitive headers that are not passed to downstream requests. Defaults to a
|
|
"safe" set of headers that commonly contain user credentials. It’s OK to remove
|
|
those from the list if the downstream service is part of the same system as the
|
|
proxy, so they are sharing authentication data. If using a physical URL outside
|
|
your own domain, then generally it would be a bad idea to leak user credentials.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.servlet-path</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>/zuul</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Path to install Zuul as a servlet (not part of Spring MVC). The servlet is more
|
|
memory efficient for requests with large bodies, e.g. file uploads.</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.ssl-hostname-validation-enabled</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag to say whether the hostname for ssl connections should be verified or not. Default is true.
|
|
This should only be used in test setups!</p></td></tr><tr><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>zuul.strip-prefix</p></td><td style="border-right: 0.5pt solid ; border-bottom: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="border-bottom: 0.5pt solid ; " align="left" valign="top"><p>Flag saying whether to strip the prefix from the path before forwarding.</p></td></tr><tr><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>zuul.trace-request-body</p></td><td style="border-right: 0.5pt solid ; " align="left" valign="top"><p>true</p></td><td style="" align="left" valign="top"><p>Flag to say that request bodies can be traced.</p></td></tr></tbody></table></div></div></div></div></body></html> |